Merge pull request #1525: Sync outdated developer API docs, add check…

… in CI
nextstrain · Jul 9, 2024 · 25be480 · 25be480
2 parents e11163d + 3e7c3d8
commit 25be480
Show file tree

Hide file tree

Showing 81 changed files with 330 additions and 140 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -209,3 +209,23 @@ jobs:
     with:
       docs-directory: docs/
       pip-install-target: .[dev]
+
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+
+      - uses: actions/checkout@v4
+
+      - run: pip install .[dev]
+
+      - run: ./devel/generate-developer-api-docs
+
+      - name: Check for changes
+        run: |
+          if [[ -n $(git status --porcelain) ]]; then
+            git add .
+            git diff --staged >&2
+            echo "There are changes to the developer API docs. Please regenerate, commit, and push the changes." >&2
+            exit 1
+          fi
diff --git a/augur/argparse_.py b/augur/argparse_.py
@@ -40,7 +40,7 @@ def add_command_subparsers(subparsers, commands, command_attribute='__command__'
         The special subparsers action object created by the parent parser
         via `parser.add_subparsers()`.
 
-    commands: list[ModuleType]
+    commands: list[types.ModuleType]
         A list of modules that are commands that require their own subparser.
         Each module is required to have a `register_parser` function to add its own
         subparser and arguments.

diff --git a/augur/curate/__init__.py b/augur/curate/__init__.py
@@ -37,7 +37,7 @@ def create_shared_parser():
     that are intended to be shared across the subcommands.
 
     Note that any options strings used here cannot be used in individual subcommand
-    subparsers unless the subparser specifically sets `conflict_handler='resolve'`²,
+    subparsers unless the subparser specifically sets `conflict_handler='resolve'` ²,
     then the subparser option will override the option defined here.
 
     Based on https://stackoverflow.com/questions/23296695/permit-argparse-global-flags-after-subcommand/23296874#23296874

diff --git a/augur/curate/apply_geolocation_rules.py b/augur/curate/apply_geolocation_rules.py
@@ -15,6 +15,9 @@ def load_geolocation_rules(geolocation_rules_file):
     """
     Loads the geolocation rules from the provided *geolocation_rules_file*.
     Returns the rules as a dict:
+
+.. code-block:: text
+
     {
         regions: {
             countries: {

diff --git a/devel/generate-developer-api-docs b/devel/generate-developer-api-docs
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+sphinx-apidoc \
+  --force \
+  --module-first \
+  --separate \
+  --no-toc \
+  --output-dir docs/api/developer \
+  augur
diff --git a/docs/api/developer/augur.align.rst b/docs/api/developer/augur.align.rst
@@ -1,5 +1,5 @@
-augur.align
-===========
+augur.align module
+==================
 
 .. automodule:: augur.align
    :members:

diff --git a/docs/api/developer/augur.ancestral.rst b/docs/api/developer/augur.ancestral.rst
@@ -1,5 +1,5 @@
-augur.ancestral
-===============
+augur.ancestral module
+======================
 
 .. automodule:: augur.ancestral
    :members:

diff --git a/docs/api/developer/augur.argparse_.rst b/docs/api/developer/augur.argparse_.rst
@@ -0,0 +1,7 @@
+augur.argparse\_ module
+=======================
+
+.. automodule:: augur.argparse_
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.clades.rst b/docs/api/developer/augur.clades.rst
@@ -1,5 +1,5 @@
-augur.clades
-============
+augur.clades module
+===================
 
 .. automodule:: augur.clades
    :members:

diff --git a/docs/api/developer/augur.curate.abbreviate_authors.rst b/docs/api/developer/augur.curate.abbreviate_authors.rst
@@ -0,0 +1,7 @@
+augur.curate.abbreviate\_authors module
+=======================================
+
+.. automodule:: augur.curate.abbreviate_authors
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.apply_geolocation_rules.rst b/docs/api/developer/augur.curate.apply_geolocation_rules.rst
@@ -0,0 +1,7 @@
+augur.curate.apply\_geolocation\_rules module
+=============================================
+
+.. automodule:: augur.curate.apply_geolocation_rules
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.apply_record_annotations.rst b/docs/api/developer/augur.curate.apply_record_annotations.rst
@@ -0,0 +1,7 @@
+augur.curate.apply\_record\_annotations module
+==============================================
+
+.. automodule:: augur.curate.apply_record_annotations
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.format_dates.rst b/docs/api/developer/augur.curate.format_dates.rst
@@ -0,0 +1,7 @@
+augur.curate.format\_dates module
+=================================
+
+.. automodule:: augur.curate.format_dates
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.format_dates_directives.rst b/docs/api/developer/augur.curate.format_dates_directives.rst
@@ -0,0 +1,7 @@
+augur.curate.format\_dates\_directives module
+=============================================
+
+.. automodule:: augur.curate.format_dates_directives
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.normalize_strings.rst b/docs/api/developer/augur.curate.normalize_strings.rst
@@ -0,0 +1,7 @@
+augur.curate.normalize\_strings module
+======================================
+
+.. automodule:: augur.curate.normalize_strings
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.parse_genbank_location.rst b/docs/api/developer/augur.curate.parse_genbank_location.rst
@@ -0,0 +1,7 @@
+augur.curate.parse\_genbank\_location module
+============================================
+
+.. automodule:: augur.curate.parse_genbank_location
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.passthru.rst b/docs/api/developer/augur.curate.passthru.rst
@@ -0,0 +1,7 @@
+augur.curate.passthru module
+============================
+
+.. automodule:: augur.curate.passthru
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.rst b/docs/api/developer/augur.curate.rst
@@ -0,0 +1,24 @@
+augur.curate package
+====================
+
+.. automodule:: augur.curate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   augur.curate.abbreviate_authors
+   augur.curate.apply_geolocation_rules
+   augur.curate.apply_record_annotations
+   augur.curate.format_dates
+   augur.curate.format_dates_directives
+   augur.curate.normalize_strings
+   augur.curate.parse_genbank_location
+   augur.curate.passthru
+   augur.curate.titlecase
+   augur.curate.transform_strain_name
diff --git a/docs/api/developer/augur.curate.titlecase.rst b/docs/api/developer/augur.curate.titlecase.rst
@@ -0,0 +1,7 @@
+augur.curate.titlecase module
+=============================
+
+.. automodule:: augur.curate.titlecase
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.curate.transform_strain_name.rst b/docs/api/developer/augur.curate.transform_strain_name.rst
@@ -0,0 +1,7 @@
+augur.curate.transform\_strain\_name module
+===========================================
+
+.. automodule:: augur.curate.transform_strain_name
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.data.rst b/docs/api/developer/augur.data.rst
@@ -0,0 +1,7 @@
+augur.data package
+==================
+
+.. automodule:: augur.data
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.dates.ambiguous_date.rst b/docs/api/developer/augur.dates.ambiguous_date.rst
@@ -1,5 +1,5 @@
-augur.dates.ambiguous\_date
-=======================================
+augur.dates.ambiguous\_date module
+==================================
 
 .. automodule:: augur.dates.ambiguous_date
    :members:

diff --git a/docs/api/developer/augur.dates.errors.rst b/docs/api/developer/augur.dates.errors.rst
@@ -1,5 +1,5 @@
-augur.dates.errors
-==================
+augur.dates.errors module
+=========================
 
 .. automodule:: augur.dates.errors
    :members:

diff --git a/docs/api/developer/augur.dates.rst b/docs/api/developer/augur.dates.rst
@@ -1,12 +1,16 @@
-augur.dates
-===========
+augur.dates package
+===================
 
 .. automodule:: augur.dates
    :members:
    :undoc-members:
    :show-inheritance:
 
+Submodules
+----------
+
 .. toctree::
+   :maxdepth: 4
 
    augur.dates.ambiguous_date
    augur.dates.errors
diff --git a/docs/api/developer/augur.distance.rst b/docs/api/developer/augur.distance.rst
@@ -1,5 +1,5 @@
-augur.distance
-==============
+augur.distance module
+=====================
 
 .. automodule:: augur.distance
    :members:

diff --git a/docs/api/developer/augur.errors.rst b/docs/api/developer/augur.errors.rst
@@ -1,5 +1,5 @@
-augur.errors
-============
+augur.errors module
+===================
 
 .. automodule:: augur.errors
    :members:

diff --git a/docs/api/developer/augur.export.rst b/docs/api/developer/augur.export.rst
@@ -1,5 +1,5 @@
-augur.export
-============
+augur.export module
+===================
 
 .. automodule:: augur.export
    :members:

diff --git a/docs/api/developer/augur.export_v1.rst b/docs/api/developer/augur.export_v1.rst
@@ -1,5 +1,5 @@
-augur.export\_v1
-================
+augur.export\_v1 module
+=======================
 
 .. automodule:: augur.export_v1
    :members:

diff --git a/docs/api/developer/augur.export_v2.rst b/docs/api/developer/augur.export_v2.rst
@@ -1,5 +1,5 @@
-augur.export\_v2
-================
+augur.export\_v2 module
+=======================
 
 .. automodule:: augur.export_v2
    :members:

diff --git a/docs/api/developer/augur.filenames.rst b/docs/api/developer/augur.filenames.rst
@@ -1,5 +1,5 @@
-augur.filenames
-===============
+augur.filenames module
+======================
 
 .. automodule:: augur.filenames
    :members:

diff --git a/docs/api/developer/augur.filter._run.rst b/docs/api/developer/augur.filter._run.rst
diff --git a/docs/api/developer/augur.filter.constants.rst b/docs/api/developer/augur.filter.constants.rst
@@ -0,0 +1,7 @@
+augur.filter.constants module
+=============================
+
+.. automodule:: augur.filter.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.filter.include_exclude_rules.rst b/docs/api/developer/augur.filter.include_exclude_rules.rst
@@ -1,5 +1,5 @@
-augur.filter.include_exclude_rules
-==================================
+augur.filter.include\_exclude\_rules module
+===========================================
 
 .. automodule:: augur.filter.include_exclude_rules
    :members:

diff --git a/docs/api/developer/augur.filter.io.rst b/docs/api/developer/augur.filter.io.rst
@@ -1,5 +1,5 @@
-augur.filter.io
-===============
+augur.filter.io module
+======================
 
 .. automodule:: augur.filter.io
    :members:

diff --git a/docs/api/developer/augur.filter.rst b/docs/api/developer/augur.filter.rst
@@ -1,14 +1,18 @@
-augur.filter
-============
+augur.filter package
+====================
 
 .. automodule:: augur.filter
    :members:
    :undoc-members:
    :show-inheritance:
 
+Submodules
+----------
+
 .. toctree::
+   :maxdepth: 4
 
-   augur.filter._run
+   augur.filter.constants
    augur.filter.include_exclude_rules
    augur.filter.io
    augur.filter.subsample

diff --git a/docs/api/developer/augur.filter.subsample.rst b/docs/api/developer/augur.filter.subsample.rst
@@ -1,5 +1,5 @@
-augur.filter.subsample
-======================
+augur.filter.subsample module
+=============================
 
 .. automodule:: augur.filter.subsample
    :members:

diff --git a/docs/api/developer/augur.filter.validate_arguments.rst b/docs/api/developer/augur.filter.validate_arguments.rst
@@ -1,5 +1,5 @@
-augur.filter.validate_arguments
-===============================
+augur.filter.validate\_arguments module
+=======================================
 
 .. automodule:: augur.filter.validate_arguments
    :members:

diff --git a/docs/api/developer/augur.frequencies.rst b/docs/api/developer/augur.frequencies.rst
@@ -1,5 +1,5 @@
-augur.frequencies
-=================
+augur.frequencies module
+========================
 
 .. automodule:: augur.frequencies
    :members:

diff --git a/docs/api/developer/augur.frequency_estimators.rst b/docs/api/developer/augur.frequency_estimators.rst
@@ -1,5 +1,5 @@
-augur.frequency\_estimators
-===========================
+augur.frequency\_estimators module
+==================================
 
 .. automodule:: augur.frequency_estimators
    :members:

diff --git a/docs/api/developer/augur.import.rst b/docs/api/developer/augur.import.rst
diff --git a/docs/api/developer/augur.import.beast.rst → docs/api/developer/augur.import_.beast.rst b/docs/api/developer/augur.import.beast.rst → docs/api/developer/augur.import_.beast.rst
@@ -1,5 +1,5 @@
-augur.import.beast
-==================
+augur.import\_.beast module
+===========================
 
 .. automodule:: augur.import_.beast
    :members: