added READMEs and simplified CI (#835)

related to #825

.github/workflows/ci_python.yml

@@ -232,7 +232,6 @@ jobs:
           poetry env use 3.11
           source $(poetry env info --path)/bin/activate
           poetry install --with=docs
-          pip install ${WHEEL} --force-reinstall
           cd docs
           python _scripts/lint_reference.py
           deactivate
@@ -242,8 +241,6 @@ jobs:
         run: |
           poetry env use 3.11
           source $(poetry env info --path)/bin/activate
-          poetry install --with=docs
-          pip install ${WHEEL} --force-reinstall
           cd docs
           python _scripts/gen_reference.py
           python -m quartodoc interlinks

python/docs/_extensions/README.md

@@ -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

python/docs/_scripts/README.md

@@ -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