Skip to content

Three competing docs configs, and no installation page or API reference #198

Open

Description

@vahid-ahmadi

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.

This also closes #84.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions