-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
added READMEs and simplified CI (#835)
related to #825
- Loading branch information
Showing
3 changed files
with
53 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
## _extensions | ||
|
||
This is where quarto extensions are vendored. | ||
|
||
#### why vendor? | ||
|
||
I (Eric) thought it would be best to not have a copy of these here, | ||
and instead install these fresh at CI run-time, but quarto | ||
recommends doing it this way. | ||
|
||
See: https://quarto.org/docs/extensions/managing.html#version-control | ||
|
||
#### updating | ||
|
||
There shouldn't be a need to update the extensions unless there is an | ||
issue or a new desired feature. To update the extensions follow the | ||
help here: https://quarto.org/docs/extensions/managing.html#updating |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
## _scripts | ||
|
||
The files in this folder are used by quartodoc to | ||
generate custom output for the Python API docs. | ||
|
||
#### custom renderer (and summarizer) | ||
|
||
Start here if you want to change any of the markdown generated for our API docs. | ||
|
||
`renderer.py` and `summarizer.py` are based off of the [default quartodoc renderer](https://github.com/machow/quartodoc/blob/main/quartodoc/renderers/md_renderer.py), | ||
split into 2 files. | ||
|
||
Both of these files use the `@dispatch` decorator to overload the same method | ||
name on many different input types. It can be tricky to find the correct | ||
method to update. | ||
|
||
#### custom builder | ||
|
||
Start here if you want to change how & where we output individual markdown files | ||
for our API docs. | ||
|
||
* `builder.py` iterates over a passed config file and then uses `renderer.py` and `summarizer.py` | ||
to output markdown for the API docs. It based off the [default quartodoc builder](https://github.com/machow/quartodoc/blob/v0.6.3/quartodoc/autosummary.py#L367), | ||
but is heavily modified. | ||
* `gen_reference.py` sets up logging, and calls `builder.py` with the `../_reference.yml` config file | ||
|
||
Note that we output files in a VERY different way than the default quartodoc executable behaves. | ||
For instance, we rely on the path of each file to build the side-bar navigation instead of | ||
generating a specific side-bar layout. | ||
|
||
#### linter | ||
|
||
This set of scripts ensures that we have included all python methods and classes in our docs. | ||
|
||
* `linter.py` is based off of `builder.py` | ||
* `lint_reference.py` sets up logging, and calls `linter.py` with the `../_reference.yml` config file |