You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Three competing docs configs, and no installation page or API reference #198
The documentation is configured three times, by two different toolchains, and the configs disagree.
/myst.yml — MyST config with a docs/-prefixed toc. This is what the deployed site builds from (deploy.yml runs myst build --html).
/docs/myst.yml — a near-duplicate MyST config with an un-prefixed toc, unused by CI and already out of sync: the root config lists docs/use_cases/scf_to_cps/imputing-from-scf-to-cps, this one stops at use_cases/index.
/docs/_config.yml and /docs/_toc.yml — legacy Jupyter Book v1, used by make documentation and by pr_docs_changes.yaml, which installs jupyter-book>=2.0.0a0, an alpha.
So the PR docs check and the published site are built by different tools from different tables of contents. The root config also has a dead entry: docs/use_cases/scf_to_cps/imputing-from-scf-to-cps is not in git.
Two related gaps in the same area:
No installation instructions in the docs.docs/index.md goes from the introduction straight to the dashboard CSV format; pip install microimpute appears only in the README.
No API reference.sphinx.ext.autodoc is declared in all three configs, but there are no autodoc or autosummary pages, so there is no rendered reference for Imputer, the five models, or autoimpute.
Suggested fix
Keep /myst.yml, delete /docs/myst.yml, /docs/_config.yml and /docs/_toc.yml, and point make documentation and pr_docs_changes.yaml at the same build the site uses. Drop the dead toc entry. Then add an installation page and an API reference.
Relevant to the JOSS submission in the paper PR: installation instructions, example usage, and API documentation are each separate items on the review checklist. Examples are well covered already — seven executable notebooks plus examples/ — so the reference is the remaining gap.
Activity