Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Sync outdated developer API docs, add check in CI #1525

Merged
merged 11 commits into from
Jul 9, 2024
Merged

Sync outdated developer API docs, add check in CI #1525

merged 11 commits into from
Jul 9, 2024

Commits on Jul 8, 2024

  1. Fix doc generation command 

    Reflects the public/developer split from a single Python API.
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    7a02b1c View commit details
    Browse the repository at this point in the history

  2. Consolidate sphinx-apidoc arguments

    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    a57a909 View commit details
    Browse the repository at this point in the history

  3. Use expanded parameter names 

    This makes it easier to understand what's going on.
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    ceac1b7 View commit details
    Browse the repository at this point in the history

  4. Auto-generate developer API docs 

    Command from dev docs:

    sphinx-apidoc \
      --force \
      --module-first \
      --separate \
      --no-toc \
      --output-dir docs/api/developer \
      augur
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    85ce264 View commit details
    Browse the repository at this point in the history

  5. Fix docs warnings 

    Warnings were:

    augur/curate/__init__.py:docstring of augur.curate.create_shared_parser:5: WARNING: Inline literal start-string without end-string.
    augur/curate/__init__.py:docstring of augur.curate.create_shared_parser:5: WARNING: Inline literal start-string without end-string.

It took some searching¹ + trial and error to figure out the fix.

¹ <sphinx-doc/sphinx#9140 (comment)>
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    7f085ae View commit details
    Browse the repository at this point in the history

  6. Fix docs warnings 

    Warnings were:

    augur/curate/apply_geolocation_rules.py:docstring of augur.curate.apply_geolocation_rules.load_geolocation_rules:9: WARNING: Definition list ends without a blank line; unexpected unindent.
    augur/curate/apply_geolocation_rules.py:docstring of augur.curate.apply_geolocation_rules.load_geolocation_rules:10: WARNING: Definition list ends without a blank line; unexpected unindent.
    augur/curate/apply_geolocation_rules.py:docstring of augur.curate.apply_geolocation_rules.load_geolocation_rules:11: WARNING: Definition list ends without a blank line; unexpected unindent.
    augur/curate/apply_geolocation_rules.py:docstring of augur.curate.apply_geolocation_rules.load_geolocation_rules:12: WARNING: Definition list ends without a blank line; unexpected unindent.
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    5d0c534 View commit details
    Browse the repository at this point in the history

  7. Suppress docs warnings for argparse._SubParsersAction 

    Warnings were:

    <unknown>:1: WARNING: py:class reference target not found: argparse._SubParsersAction
    <unknown>:1: WARNING: py:class reference target not found: argparse._SubParsersAction
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    048d372 View commit details
    Browse the repository at this point in the history

  8. Fix warning for type reference

    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    f5007b6 View commit details
    Browse the repository at this point in the history

  9. Fix warnings of duplicate object descriptions for unused files 

    These files are not referenced by the auto-generated docs.
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    597537e View commit details
    Browse the repository at this point in the history

  10. Fix warning for duplicate object description of augur.io 

    Since augur.io is in both the public and developer APIs, only one can be
used for cross referencing meaning the other must have `:noindex:`.

Ideally the developer API docs would have `:noindex:` so the public API
docs can list all exported functions on its index page. However,
regenerating the developer API docs using sphinx-apidoc will remove the
`:noindex:` so that's not a direct option without digging further.
    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    50768fe View commit details
    Browse the repository at this point in the history

  11. Move sphinx-apidoc command to script and run in CI

    @victorlin
    victorlin committed Jul 8, 2024
    Configuration menu
    Copy the full SHA
    3e7c3d8 View commit details
    Browse the repository at this point in the history