Merge pull request #1527: Clarify steps to regenerate developer API docs

nextstrain · Jul 10, 2024 · 81badd2 · 81badd2
2 parents 6bc39c1 + 0f60f36
commit 81badd2
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 11 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -219,13 +219,14 @@ jobs:
 
       - run: pip install .[dev]
 
-      - run: ./devel/generate-developer-api-docs
+      - run: ./devel/regenerate-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
+            echo "There are changes that affect the developer API docs. Please update: <https://github.com/nextstrain/augur/blob/-/docs/contribute/DEV_DOCS.md#regenerating-developer-api-docs>" >&2
+            echo "If there are changes to the Augur CLI, please manually adjust files under 'docs/usage/cli/'." >&2
             exit 1
           fi
diff --git a/devel/generate-developer-api-docs → devel/regenerate-developer-api-docs b/devel/generate-developer-api-docs → devel/regenerate-developer-api-docs
@@ -1,5 +1,7 @@
 #!/bin/bash
 
+rm -f docs/api/developer/augur.*
+
 sphinx-apidoc \
   --force \
   --module-first \

diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md
@@ -319,10 +319,20 @@ Python file must be accompanied by at least one corresponding reStructuredText
 file in order to render the pages.
 
 - If a new Python file is added, a new reStructuredText file should be added
-  under `docs/api/`.
+  under `docs/api/developer`. This can be done
+  [using a script](#regenerating-developer-api-docs).
 - If the new Python file represents a subcommand of `augur`, a new
   reStructuredText file should be added under `docs/usage/cli/` in addition to
-  the new file under `docs/api/`.
+  the new file under `docs/api/developer`.
+
+### Regenerating developer API docs
+
+To regenerate the developer API documentation after adding, renaming, or removing an augur
+submodule, autogenerate a new API file as follows.
+
+```bash
+./devel/regenerate-developer-api-docs
+```
 
 ### Building documentation
 
@@ -357,13 +367,6 @@ Sphinx can build other formats, such as epub. To see other available formats, ru
 make -C docs help
 ```
 
-To update the developer API documentation after adding or removing an augur submodule,
-autogenerate a new API file as follows.
-
-```bash
-./devel/generate-developer-api-docs
-```
-
 To make doc rebuilds faster, Sphinx caches built documentation by default,
 which is generally great, but can cause the sidebar of pages to be stale.
 You can clean out the cache with: