From 7a02b1cf7a3ed0302eb95dd2dc368a3a515b8d2a Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 11:47:20 -0700 Subject: [PATCH 01/11] Fix doc generation command Reflects the public/developer split from a single Python API. --- docs/contribute/DEV_DOCS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index e9a26c2cc..b477f124b 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -333,11 +333,11 @@ Sphinx can build other formats, such as epub. To see other available formats, ru make -C docs help ``` -To update the API documentation after adding or removing an augur submodule, +To update the developer API documentation after adding or removing an augur submodule, autogenerate a new API file as follows. ```bash -sphinx-apidoc -T -f -MeT -o docs/api augur +sphinx-apidoc -T -f -MeT -o docs/api/developer augur ``` To make doc rebuilds faster, Sphinx caches built documentation by default, From a57a9090b651870eea06cc762c1f4b906bc28aeb Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 11:48:06 -0700 Subject: [PATCH 02/11] Consolidate sphinx-apidoc arguments --- docs/contribute/DEV_DOCS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index b477f124b..47654ad8d 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -337,7 +337,7 @@ To update the developer API documentation after adding or removing an augur subm autogenerate a new API file as follows. ```bash -sphinx-apidoc -T -f -MeT -o docs/api/developer augur +sphinx-apidoc -fMeT -o docs/api/developer augur ``` To make doc rebuilds faster, Sphinx caches built documentation by default, From ceac1b7aa0a449f7f1d13eca3065b98ef6f1931b Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 11:52:50 -0700 Subject: [PATCH 03/11] Use expanded parameter names This makes it easier to understand what's going on. --- docs/contribute/DEV_DOCS.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index 47654ad8d..213e006b8 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -337,7 +337,13 @@ To update the developer API documentation after adding or removing an augur subm autogenerate a new API file as follows. ```bash -sphinx-apidoc -fMeT -o docs/api/developer augur +sphinx-apidoc \ + --force \ + --module-first \ + --separate \ + --no-toc \ + --output-dir docs/api/developer \ + augur ``` To make doc rebuilds faster, Sphinx caches built documentation by default, From 85ce264110146457859df6388d6680f2e8012b9d Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 12:00:35 -0700 Subject: [PATCH 04/11] Auto-generate developer API docs Command from dev docs: sphinx-apidoc \ --force \ --module-first \ --separate \ --no-toc \ --output-dir docs/api/developer \ augur --- docs/api/developer/augur.align.rst | 4 +-- docs/api/developer/augur.ancestral.rst | 4 +-- docs/api/developer/augur.argparse_.rst | 7 +++++ docs/api/developer/augur.clades.rst | 4 +-- .../augur.curate.abbreviate_authors.rst | 7 +++++ .../augur.curate.apply_geolocation_rules.rst | 7 +++++ .../augur.curate.apply_record_annotations.rst | 7 +++++ .../developer/augur.curate.format_dates.rst | 7 +++++ .../augur.curate.format_dates_directives.rst | 7 +++++ .../augur.curate.normalize_strings.rst | 7 +++++ .../augur.curate.parse_genbank_location.rst | 7 +++++ docs/api/developer/augur.curate.passthru.rst | 7 +++++ docs/api/developer/augur.curate.rst | 24 +++++++++++++++ docs/api/developer/augur.curate.titlecase.rst | 7 +++++ .../augur.curate.transform_strain_name.rst | 7 +++++ docs/api/developer/augur.data.rst | 7 +++++ .../developer/augur.dates.ambiguous_date.rst | 4 +-- docs/api/developer/augur.dates.errors.rst | 4 +-- docs/api/developer/augur.dates.rst | 8 +++-- docs/api/developer/augur.distance.rst | 4 +-- docs/api/developer/augur.errors.rst | 4 +-- docs/api/developer/augur.export.rst | 4 +-- docs/api/developer/augur.export_v1.rst | 4 +-- docs/api/developer/augur.export_v2.rst | 4 +-- docs/api/developer/augur.filenames.rst | 4 +-- docs/api/developer/augur.filter.constants.rst | 7 +++++ .../augur.filter.include_exclude_rules.rst | 4 +-- docs/api/developer/augur.filter.io.rst | 4 +-- docs/api/developer/augur.filter.rst | 10 +++++-- docs/api/developer/augur.filter.subsample.rst | 4 +-- .../augur.filter.validate_arguments.rst | 4 +-- docs/api/developer/augur.frequencies.rst | 4 +-- .../developer/augur.frequency_estimators.rst | 4 +-- docs/api/developer/augur.import_.beast.rst | 7 +++++ docs/api/developer/augur.import_.rst | 15 ++++++++++ docs/api/developer/augur.index.rst | 4 +-- docs/api/developer/augur.io.file.rst | 4 +-- docs/api/developer/augur.io.json.rst | 4 +-- docs/api/developer/augur.io.metadata.rst | 4 +-- docs/api/developer/augur.io.print.rst | 4 +-- docs/api/developer/augur.io.rst | 10 +++++-- docs/api/developer/augur.io.sequences.rst | 4 +-- .../augur.io.shell_command_runner.rst | 4 +-- docs/api/developer/augur.io.strains.rst | 7 +++++ docs/api/developer/augur.io.vcf.rst | 4 +-- docs/api/developer/augur.lbi.rst | 4 +-- docs/api/developer/augur.mask.rst | 4 +-- .../developer/augur.measurements.concat.rst | 4 +-- .../developer/augur.measurements.export.rst | 4 +-- docs/api/developer/augur.measurements.rst | 8 +++-- docs/api/developer/augur.parse.rst | 4 +-- .../developer/augur.reconstruct_sequences.rst | 4 +-- docs/api/developer/augur.refine.rst | 4 +-- docs/api/developer/augur.rst | 30 ++++++++++++++----- docs/api/developer/augur.sequence_traits.rst | 4 +-- docs/api/developer/augur.titer_model.rst | 4 +-- docs/api/developer/augur.titers.rst | 4 +-- docs/api/developer/augur.traits.rst | 4 +-- docs/api/developer/augur.translate.rst | 4 +-- docs/api/developer/augur.tree.rst | 4 +-- docs/api/developer/augur.types.rst | 4 +-- .../augur.util_support.color_parser.rst | 4 +-- .../augur.util_support.color_parser_line.rst | 4 +-- .../augur.util_support.node_data.rst | 4 +-- .../augur.util_support.node_data_file.rst | 4 +-- .../augur.util_support.node_data_reader.rst | 4 +-- docs/api/developer/augur.util_support.rst | 8 +++-- docs/api/developer/augur.utils.rst | 4 +-- docs/api/developer/augur.validate.rst | 4 +-- docs/api/developer/augur.validate_export.rst | 4 +-- docs/api/developer/augur.version.rst | 4 +-- 71 files changed, 294 insertions(+), 116 deletions(-) create mode 100644 docs/api/developer/augur.argparse_.rst create mode 100644 docs/api/developer/augur.curate.abbreviate_authors.rst create mode 100644 docs/api/developer/augur.curate.apply_geolocation_rules.rst create mode 100644 docs/api/developer/augur.curate.apply_record_annotations.rst create mode 100644 docs/api/developer/augur.curate.format_dates.rst create mode 100644 docs/api/developer/augur.curate.format_dates_directives.rst create mode 100644 docs/api/developer/augur.curate.normalize_strings.rst create mode 100644 docs/api/developer/augur.curate.parse_genbank_location.rst create mode 100644 docs/api/developer/augur.curate.passthru.rst create mode 100644 docs/api/developer/augur.curate.rst create mode 100644 docs/api/developer/augur.curate.titlecase.rst create mode 100644 docs/api/developer/augur.curate.transform_strain_name.rst create mode 100644 docs/api/developer/augur.data.rst create mode 100644 docs/api/developer/augur.filter.constants.rst create mode 100644 docs/api/developer/augur.import_.beast.rst create mode 100644 docs/api/developer/augur.import_.rst create mode 100644 docs/api/developer/augur.io.strains.rst diff --git a/docs/api/developer/augur.align.rst b/docs/api/developer/augur.align.rst index 08c87d3c1..8d6393108 100644 --- 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 index 4bae58280..8a25bd315 100644 --- 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 new file mode 100644 index 000000000..e24668843 --- /dev/null +++ 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 index 34e5fa013..738727997 100644 --- 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 new file mode 100644 index 000000000..f41729bd0 --- /dev/null +++ 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 new file mode 100644 index 000000000..fa6e95c8e --- /dev/null +++ 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 new file mode 100644 index 000000000..8d360eade --- /dev/null +++ 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 new file mode 100644 index 000000000..35e697563 --- /dev/null +++ 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 new file mode 100644 index 000000000..80891975d --- /dev/null +++ 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 new file mode 100644 index 000000000..19de55aa0 --- /dev/null +++ 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 new file mode 100644 index 000000000..cbad6ee2b --- /dev/null +++ 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 new file mode 100644 index 000000000..87e481733 --- /dev/null +++ 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 new file mode 100644 index 000000000..529991e6f --- /dev/null +++ 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 new file mode 100644 index 000000000..3580664a8 --- /dev/null +++ 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 new file mode 100644 index 000000000..60cac247d --- /dev/null +++ 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 new file mode 100644 index 000000000..6594d4b8c --- /dev/null +++ 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 index 2471f3e8f..8d807ef38 100644 --- 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 index d4da219fc..a7fae8e9d 100644 --- 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 index 5f314f3ce..5f73f4cc0 100644 --- 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 index a93e87060..849f73212 100644 --- 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 index b35076ca3..3b6964961 100644 --- 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 index 1941432a8..cbfd13529 100644 --- 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 index f743ee776..7cde9fb15 100644 --- 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 index 885607702..d08be029a 100644 --- 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 index 0eedd7018..34be1fd42 100644 --- 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.constants.rst b/docs/api/developer/augur.filter.constants.rst new file mode 100644 index 000000000..d0551e5d5 --- /dev/null +++ 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 index 07801f93d..6c62dd6b1 100644 --- 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 index e86915ce3..6e74a4db7 100644 --- 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 index c8fab2d7e..44942a2fd 100644 --- 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 index 64bc10d7b..af826b05d 100644 --- 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 index a91c9d11d..af5fe79ff 100644 --- 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 index 266a564a5..e45b7fdd4 100644 --- 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 index b48df2f28..0d1ec6489 100644 --- 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_.beast.rst b/docs/api/developer/augur.import_.beast.rst new file mode 100644 index 000000000..c33a9c9c8 --- /dev/null +++ b/docs/api/developer/augur.import_.beast.rst @@ -0,0 +1,7 @@ +augur.import\_.beast module +=========================== + +.. automodule:: augur.import_.beast + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/developer/augur.import_.rst b/docs/api/developer/augur.import_.rst new file mode 100644 index 000000000..741f610bf --- /dev/null +++ b/docs/api/developer/augur.import_.rst @@ -0,0 +1,15 @@ +augur.import\_ package +====================== + +.. automodule:: augur.import_ + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + augur.import_.beast diff --git a/docs/api/developer/augur.index.rst b/docs/api/developer/augur.index.rst index 65f8c9c9d..f8b1f4a10 100644 --- a/docs/api/developer/augur.index.rst +++ b/docs/api/developer/augur.index.rst @@ -1,5 +1,5 @@ -augur.index -=========== +augur.index module +================== .. automodule:: augur.index :members: diff --git a/docs/api/developer/augur.io.file.rst b/docs/api/developer/augur.io.file.rst index 82b052327..54e8056a0 100644 --- a/docs/api/developer/augur.io.file.rst +++ b/docs/api/developer/augur.io.file.rst @@ -1,5 +1,5 @@ -augur.io.file -============= +augur.io.file module +==================== .. automodule:: augur.io.file :members: diff --git a/docs/api/developer/augur.io.json.rst b/docs/api/developer/augur.io.json.rst index ee0811783..b6adbe1d8 100644 --- a/docs/api/developer/augur.io.json.rst +++ b/docs/api/developer/augur.io.json.rst @@ -1,5 +1,5 @@ -augur.io.json -============= +augur.io.json module +==================== .. automodule:: augur.io.json :members: diff --git a/docs/api/developer/augur.io.metadata.rst b/docs/api/developer/augur.io.metadata.rst index bdc462596..caaa0c910 100644 --- a/docs/api/developer/augur.io.metadata.rst +++ b/docs/api/developer/augur.io.metadata.rst @@ -1,5 +1,5 @@ -augur.io.metadata -================= +augur.io.metadata module +======================== .. automodule:: augur.io.metadata :members: diff --git a/docs/api/developer/augur.io.print.rst b/docs/api/developer/augur.io.print.rst index 536977d3e..6f73b5a71 100644 --- a/docs/api/developer/augur.io.print.rst +++ b/docs/api/developer/augur.io.print.rst @@ -1,5 +1,5 @@ -augur.io.print -============== +augur.io.print module +===================== .. automodule:: augur.io.print :members: diff --git a/docs/api/developer/augur.io.rst b/docs/api/developer/augur.io.rst index 13c044f60..d6db9a2b2 100644 --- a/docs/api/developer/augur.io.rst +++ b/docs/api/developer/augur.io.rst @@ -1,13 +1,16 @@ -augur.io -======== +augur.io package +================ .. automodule:: augur.io :members: :undoc-members: :show-inheritance: - :noindex: + +Submodules +---------- .. toctree:: + :maxdepth: 4 augur.io.file augur.io.json @@ -15,4 +18,5 @@ augur.io augur.io.print augur.io.sequences augur.io.shell_command_runner + augur.io.strains augur.io.vcf diff --git a/docs/api/developer/augur.io.sequences.rst b/docs/api/developer/augur.io.sequences.rst index 1ed60dd4b..da25ac1c9 100644 --- a/docs/api/developer/augur.io.sequences.rst +++ b/docs/api/developer/augur.io.sequences.rst @@ -1,5 +1,5 @@ -augur.io.sequences -================== +augur.io.sequences module +========================= .. automodule:: augur.io.sequences :members: diff --git a/docs/api/developer/augur.io.shell_command_runner.rst b/docs/api/developer/augur.io.shell_command_runner.rst index b77af7ab9..97f286186 100644 --- a/docs/api/developer/augur.io.shell_command_runner.rst +++ b/docs/api/developer/augur.io.shell_command_runner.rst @@ -1,5 +1,5 @@ -augur.io.shell_command_runner -============================= +augur.io.shell\_command\_runner module +====================================== .. automodule:: augur.io.shell_command_runner :members: diff --git a/docs/api/developer/augur.io.strains.rst b/docs/api/developer/augur.io.strains.rst new file mode 100644 index 000000000..92133034e --- /dev/null +++ b/docs/api/developer/augur.io.strains.rst @@ -0,0 +1,7 @@ +augur.io.strains module +======================= + +.. automodule:: augur.io.strains + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/developer/augur.io.vcf.rst b/docs/api/developer/augur.io.vcf.rst index d75bddf1d..16ee195b1 100644 --- a/docs/api/developer/augur.io.vcf.rst +++ b/docs/api/developer/augur.io.vcf.rst @@ -1,5 +1,5 @@ -augur.io.vcf -============ +augur.io.vcf module +=================== .. automodule:: augur.io.vcf :members: diff --git a/docs/api/developer/augur.lbi.rst b/docs/api/developer/augur.lbi.rst index 70599bde1..c58ef36cc 100644 --- a/docs/api/developer/augur.lbi.rst +++ b/docs/api/developer/augur.lbi.rst @@ -1,5 +1,5 @@ -augur.lbi -========= +augur.lbi module +================ .. automodule:: augur.lbi :members: diff --git a/docs/api/developer/augur.mask.rst b/docs/api/developer/augur.mask.rst index 8d1f5c250..27dc7e357 100644 --- a/docs/api/developer/augur.mask.rst +++ b/docs/api/developer/augur.mask.rst @@ -1,5 +1,5 @@ -augur.mask -========== +augur.mask module +================= .. automodule:: augur.mask :members: diff --git a/docs/api/developer/augur.measurements.concat.rst b/docs/api/developer/augur.measurements.concat.rst index 1a257f323..a446e4e57 100644 --- a/docs/api/developer/augur.measurements.concat.rst +++ b/docs/api/developer/augur.measurements.concat.rst @@ -1,5 +1,5 @@ -augur.measurements.concat -========================= +augur.measurements.concat module +================================ .. automodule:: augur.measurements.concat :members: diff --git a/docs/api/developer/augur.measurements.export.rst b/docs/api/developer/augur.measurements.export.rst index 8850aea05..b0ac57198 100644 --- a/docs/api/developer/augur.measurements.export.rst +++ b/docs/api/developer/augur.measurements.export.rst @@ -1,5 +1,5 @@ -augur.measurements.export -========================= +augur.measurements.export module +================================ .. automodule:: augur.measurements.export :members: diff --git a/docs/api/developer/augur.measurements.rst b/docs/api/developer/augur.measurements.rst index e9f59e79f..a7e32f7c1 100644 --- a/docs/api/developer/augur.measurements.rst +++ b/docs/api/developer/augur.measurements.rst @@ -1,12 +1,16 @@ -augur.measurements -================== +augur.measurements package +========================== .. automodule:: augur.measurements :members: :undoc-members: :show-inheritance: +Submodules +---------- + .. toctree:: + :maxdepth: 4 augur.measurements.concat augur.measurements.export diff --git a/docs/api/developer/augur.parse.rst b/docs/api/developer/augur.parse.rst index 071c89262..fb1511e75 100644 --- a/docs/api/developer/augur.parse.rst +++ b/docs/api/developer/augur.parse.rst @@ -1,5 +1,5 @@ -augur.parse -=========== +augur.parse module +================== .. automodule:: augur.parse :members: diff --git a/docs/api/developer/augur.reconstruct_sequences.rst b/docs/api/developer/augur.reconstruct_sequences.rst index f10ed1632..deb7ec700 100644 --- a/docs/api/developer/augur.reconstruct_sequences.rst +++ b/docs/api/developer/augur.reconstruct_sequences.rst @@ -1,5 +1,5 @@ -augur.reconstruct\_sequences -============================ +augur.reconstruct\_sequences module +=================================== .. automodule:: augur.reconstruct_sequences :members: diff --git a/docs/api/developer/augur.refine.rst b/docs/api/developer/augur.refine.rst index d3a036248..409b23939 100644 --- a/docs/api/developer/augur.refine.rst +++ b/docs/api/developer/augur.refine.rst @@ -1,5 +1,5 @@ -augur.refine -============ +augur.refine module +=================== .. automodule:: augur.refine :members: diff --git a/docs/api/developer/augur.rst b/docs/api/developer/augur.rst index d7fc72359..1afda35bc 100644 --- a/docs/api/developer/augur.rst +++ b/docs/api/developer/augur.rst @@ -1,32 +1,47 @@ -augur -===== +augur package +============= .. automodule:: augur :members: :undoc-members: :show-inheritance: +Subpackages +----------- + .. toctree:: + :maxdepth: 4 + + augur.curate + augur.data + augur.dates + augur.filter + augur.import_ + augur.io + augur.measurements + augur.util_support + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 augur.align augur.ancestral + augur.argparse_ augur.clades - augur.dates augur.distance augur.errors augur.export augur.export_v1 augur.export_v2 augur.filenames - augur.filter augur.frequencies augur.frequency_estimators - augur.import augur.index - augur.io augur.lbi augur.mask - augur.measurements augur.parse augur.reconstruct_sequences augur.refine @@ -37,7 +52,6 @@ augur augur.translate augur.tree augur.types - augur.util_support augur.utils augur.validate augur.validate_export diff --git a/docs/api/developer/augur.sequence_traits.rst b/docs/api/developer/augur.sequence_traits.rst index 33316abba..39f2faccf 100644 --- a/docs/api/developer/augur.sequence_traits.rst +++ b/docs/api/developer/augur.sequence_traits.rst @@ -1,5 +1,5 @@ -augur.sequence\_traits -====================== +augur.sequence\_traits module +============================= .. automodule:: augur.sequence_traits :members: diff --git a/docs/api/developer/augur.titer_model.rst b/docs/api/developer/augur.titer_model.rst index 404e917ab..405093084 100644 --- a/docs/api/developer/augur.titer_model.rst +++ b/docs/api/developer/augur.titer_model.rst @@ -1,5 +1,5 @@ -augur.titer\_model -================== +augur.titer\_model module +========================= .. automodule:: augur.titer_model :members: diff --git a/docs/api/developer/augur.titers.rst b/docs/api/developer/augur.titers.rst index fcb8dc534..a2d0bbedf 100644 --- a/docs/api/developer/augur.titers.rst +++ b/docs/api/developer/augur.titers.rst @@ -1,5 +1,5 @@ -augur.titers -============ +augur.titers module +=================== .. automodule:: augur.titers :members: diff --git a/docs/api/developer/augur.traits.rst b/docs/api/developer/augur.traits.rst index ddc2cd024..912997a4d 100644 --- a/docs/api/developer/augur.traits.rst +++ b/docs/api/developer/augur.traits.rst @@ -1,5 +1,5 @@ -augur.traits -============ +augur.traits module +=================== .. automodule:: augur.traits :members: diff --git a/docs/api/developer/augur.translate.rst b/docs/api/developer/augur.translate.rst index af5f0d647..8303ece8a 100644 --- a/docs/api/developer/augur.translate.rst +++ b/docs/api/developer/augur.translate.rst @@ -1,5 +1,5 @@ -augur.translate -=============== +augur.translate module +====================== .. automodule:: augur.translate :members: diff --git a/docs/api/developer/augur.tree.rst b/docs/api/developer/augur.tree.rst index 6611ca145..59db44a14 100644 --- a/docs/api/developer/augur.tree.rst +++ b/docs/api/developer/augur.tree.rst @@ -1,5 +1,5 @@ -augur.tree -========== +augur.tree module +================= .. automodule:: augur.tree :members: diff --git a/docs/api/developer/augur.types.rst b/docs/api/developer/augur.types.rst index d37872b71..c64003bdd 100644 --- a/docs/api/developer/augur.types.rst +++ b/docs/api/developer/augur.types.rst @@ -1,5 +1,5 @@ -augur.types -=========== +augur.types module +================== .. automodule:: augur.types :members: diff --git a/docs/api/developer/augur.util_support.color_parser.rst b/docs/api/developer/augur.util_support.color_parser.rst index 9f93912fd..89a47b1af 100644 --- a/docs/api/developer/augur.util_support.color_parser.rst +++ b/docs/api/developer/augur.util_support.color_parser.rst @@ -1,5 +1,5 @@ -augur.util\_support.color\_parser -================================= +augur.util\_support.color\_parser module +======================================== .. automodule:: augur.util_support.color_parser :members: diff --git a/docs/api/developer/augur.util_support.color_parser_line.rst b/docs/api/developer/augur.util_support.color_parser_line.rst index 737977f0b..264fe69d3 100644 --- a/docs/api/developer/augur.util_support.color_parser_line.rst +++ b/docs/api/developer/augur.util_support.color_parser_line.rst @@ -1,5 +1,5 @@ -augur.util\_support.color\_parser\_line -======================================= +augur.util\_support.color\_parser\_line module +============================================== .. automodule:: augur.util_support.color_parser_line :members: diff --git a/docs/api/developer/augur.util_support.node_data.rst b/docs/api/developer/augur.util_support.node_data.rst index 017478b8a..69b4368ab 100644 --- a/docs/api/developer/augur.util_support.node_data.rst +++ b/docs/api/developer/augur.util_support.node_data.rst @@ -1,5 +1,5 @@ -augur.util\_support.node\_data -============================== +augur.util\_support.node\_data module +===================================== .. automodule:: augur.util_support.node_data :members: diff --git a/docs/api/developer/augur.util_support.node_data_file.rst b/docs/api/developer/augur.util_support.node_data_file.rst index c4f59e1c2..568e9b885 100644 --- a/docs/api/developer/augur.util_support.node_data_file.rst +++ b/docs/api/developer/augur.util_support.node_data_file.rst @@ -1,5 +1,5 @@ -augur.util\_support.node\_data\_file -==================================== +augur.util\_support.node\_data\_file module +=========================================== .. automodule:: augur.util_support.node_data_file :members: diff --git a/docs/api/developer/augur.util_support.node_data_reader.rst b/docs/api/developer/augur.util_support.node_data_reader.rst index 5c2c4df19..ce85ee592 100644 --- a/docs/api/developer/augur.util_support.node_data_reader.rst +++ b/docs/api/developer/augur.util_support.node_data_reader.rst @@ -1,5 +1,5 @@ -augur.util\_support.node\_data\_reader -====================================== +augur.util\_support.node\_data\_reader module +============================================= .. automodule:: augur.util_support.node_data_reader :members: diff --git a/docs/api/developer/augur.util_support.rst b/docs/api/developer/augur.util_support.rst index 0c20d9f1e..3eaf5bd77 100644 --- a/docs/api/developer/augur.util_support.rst +++ b/docs/api/developer/augur.util_support.rst @@ -1,12 +1,16 @@ -augur.util\_support -=================== +augur.util\_support package +=========================== .. automodule:: augur.util_support :members: :undoc-members: :show-inheritance: +Submodules +---------- + .. toctree:: + :maxdepth: 4 augur.util_support.color_parser augur.util_support.color_parser_line diff --git a/docs/api/developer/augur.utils.rst b/docs/api/developer/augur.utils.rst index 4c6e363ad..fc0e6b8c4 100644 --- a/docs/api/developer/augur.utils.rst +++ b/docs/api/developer/augur.utils.rst @@ -1,5 +1,5 @@ -augur.utils -=========== +augur.utils module +================== .. automodule:: augur.utils :members: diff --git a/docs/api/developer/augur.validate.rst b/docs/api/developer/augur.validate.rst index 7a299f64b..9bace5148 100644 --- a/docs/api/developer/augur.validate.rst +++ b/docs/api/developer/augur.validate.rst @@ -1,5 +1,5 @@ -augur.validate -============== +augur.validate module +===================== .. automodule:: augur.validate :members: diff --git a/docs/api/developer/augur.validate_export.rst b/docs/api/developer/augur.validate_export.rst index 33e225e6d..5cc90837b 100644 --- a/docs/api/developer/augur.validate_export.rst +++ b/docs/api/developer/augur.validate_export.rst @@ -1,5 +1,5 @@ -augur.validate\_export -====================== +augur.validate\_export module +============================= .. automodule:: augur.validate_export :members: diff --git a/docs/api/developer/augur.version.rst b/docs/api/developer/augur.version.rst index 7ee6db25b..f9e59e43a 100644 --- a/docs/api/developer/augur.version.rst +++ b/docs/api/developer/augur.version.rst @@ -1,5 +1,5 @@ -augur.version -============= +augur.version module +==================== .. automodule:: augur.version :members: From 7f085ae75c78b05f5bd2fff8533ce3555db5aa2d Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Tue, 2 Jul 2024 16:56:15 -0700 Subject: [PATCH 05/11] Fix docs warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. ¹ --- augur/curate/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/augur/curate/__init__.py b/augur/curate/__init__.py index ea0196061..5e6dcb0a8 100644 --- a/augur/curate/__init__.py +++ b/augur/curate/__init__.py @@ -36,7 +36,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 From 5d0c5347b2b7794873b6d2fffa0d630a5886a32a Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Tue, 2 Jul 2024 17:14:21 -0700 Subject: [PATCH 06/11] 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. --- augur/curate/apply_geolocation_rules.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/augur/curate/apply_geolocation_rules.py b/augur/curate/apply_geolocation_rules.py index 7c167a9cf..e14974890 100644 --- 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: { From 048d37268253db4403679fbd9aed6d45cfe4e939 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 11:16:32 -0700 Subject: [PATCH 07/11] Suppress docs warnings for argparse._SubParsersAction Warnings were: :1: WARNING: py:class reference target not found: argparse._SubParsersAction :1: WARNING: py:class reference target not found: argparse._SubParsersAction --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index b072803fc..1a97a5d65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -131,6 +131,10 @@ def prose_list(items): # resolved by intersphinx for a proper link. ("py:class", "json.decoder.JSONDecodeError"), ("py:class", "json.encoder.JSONEncoder"), + + # This class can't be referenced. + # + ("py:class", "argparse._SubParsersAction"), ] # -- Cross-project references ------------------------------------------------ From f5007b63e30a47376ed36758c9317a91bd90ed46 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 12:26:40 -0700 Subject: [PATCH 08/11] Fix warning for type reference --- augur/argparse_.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/augur/argparse_.py b/augur/argparse_.py index 6a535b430..6f0ee5e72 100644 --- 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. From 597537e220c8cead991645c4df1c5451a33bcbee Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 14:09:00 -0700 Subject: [PATCH 09/11] Fix warnings of duplicate object descriptions for unused files These files are not referenced by the auto-generated docs. --- docs/api/developer/augur.filter._run.rst | 7 ------- docs/api/developer/augur.import.beast.rst | 7 ------- docs/api/developer/augur.import.rst | 11 ----------- 3 files changed, 25 deletions(-) delete mode 100644 docs/api/developer/augur.filter._run.rst delete mode 100644 docs/api/developer/augur.import.beast.rst delete mode 100644 docs/api/developer/augur.import.rst diff --git a/docs/api/developer/augur.filter._run.rst b/docs/api/developer/augur.filter._run.rst deleted file mode 100644 index 989429705..000000000 --- a/docs/api/developer/augur.filter._run.rst +++ /dev/null @@ -1,7 +0,0 @@ -augur.filter._run -================= - -.. automodule:: augur.filter._run - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/api/developer/augur.import.beast.rst b/docs/api/developer/augur.import.beast.rst deleted file mode 100644 index 72910cfaa..000000000 --- a/docs/api/developer/augur.import.beast.rst +++ /dev/null @@ -1,7 +0,0 @@ -augur.import.beast -================== - -.. automodule:: augur.import_.beast - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/api/developer/augur.import.rst b/docs/api/developer/augur.import.rst deleted file mode 100644 index d53159955..000000000 --- a/docs/api/developer/augur.import.rst +++ /dev/null @@ -1,11 +0,0 @@ -augur.import -============ - -.. automodule:: augur.import_ - :members: - :undoc-members: - :show-inheritance: - -.. toctree:: - - augur.import.beast From 50768feff92f9005e6f603fedd0b976f04a36761 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 14:11:19 -0700 Subject: [PATCH 10/11] 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. --- docs/api/public/augur.io.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api/public/augur.io.rst b/docs/api/public/augur.io.rst index 4b9b6880f..36d0fcf8c 100644 --- a/docs/api/public/augur.io.rst +++ b/docs/api/public/augur.io.rst @@ -8,3 +8,4 @@ augur.io :imported-members: :undoc-members: :show-inheritance: + :noindex: From 3e7c3d8e3a1e0dcd457305b4f7510a0b58e9b4ed Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 3 Jul 2024 14:40:43 -0700 Subject: [PATCH 11/11] Move sphinx-apidoc command to script and run in CI --- .github/workflows/ci.yaml | 20 ++++++++++++++++++++ devel/generate-developer-api-docs | 9 +++++++++ docs/contribute/DEV_DOCS.md | 8 +------- 3 files changed, 30 insertions(+), 7 deletions(-) create mode 100755 devel/generate-developer-api-docs diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index f1bc75b65..db440c8f1 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -188,3 +188,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/devel/generate-developer-api-docs b/devel/generate-developer-api-docs new file mode 100755 index 000000000..235464bdb --- /dev/null +++ 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/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index 213e006b8..81e816ee6 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -337,13 +337,7 @@ To update the developer API documentation after adding or removing an augur subm autogenerate a new API file as follows. ```bash -sphinx-apidoc \ - --force \ - --module-first \ - --separate \ - --no-toc \ - --output-dir docs/api/developer \ - augur +./devel/generate-developer-api-docs ``` To make doc rebuilds faster, Sphinx caches built documentation by default,