From 86eaca9291184ca40838c42c87372eec4845738a Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 10 Jul 2024 13:59:32 -0700 Subject: [PATCH 1/5] Support deletions and renames in devel/generate-developer-api-docs To match instructions in DEV_DOCS.md. --- devel/generate-developer-api-docs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devel/generate-developer-api-docs b/devel/generate-developer-api-docs index 235464bdb..dbb01fd54 100755 --- a/devel/generate-developer-api-docs +++ b/devel/generate-developer-api-docs @@ -1,5 +1,7 @@ #!/bin/bash +rm -f docs/api/developer/augur.* + sphinx-apidoc \ --force \ --module-first \ From 6ca5cce40903fa396f87663bb2d90d42e6e489d3 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 10 Jul 2024 13:50:03 -0700 Subject: [PATCH 2/5] Make new section for devel/generate-developer-api-docs To be referenced elsewhere. --- docs/contribute/DEV_DOCS.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index 4fc9598ec..a76ecf2fc 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -324,6 +324,15 @@ file in order to render the pages. reStructuredText file should be added under `docs/usage/cli/` in addition to the new file under `docs/api/`. +### Automatically updating developer API docs + +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 +``` + ### Building documentation Building the documentation locally is useful to test changes. @@ -357,13 +366,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: From 6c75a8b8bcacc48a4b485cb1ca1b484d4308433f Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 10 Jul 2024 14:06:38 -0700 Subject: [PATCH 3/5] Update wording around regenerating developer API docs The old wording said "automatic" which is not entirely accurate since you still have to manually commit and push the changes. --- .github/workflows/ci.yaml | 2 +- ...e-developer-api-docs => regenerate-developer-api-docs} | 0 docs/contribute/DEV_DOCS.md | 8 ++++---- 3 files changed, 5 insertions(+), 5 deletions(-) rename devel/{generate-developer-api-docs => regenerate-developer-api-docs} (100%) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 2f6c89e5a..82ea46e28 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -219,7 +219,7 @@ jobs: - run: pip install .[dev] - - run: ./devel/generate-developer-api-docs + - run: ./devel/regenerate-developer-api-docs - name: Check for changes run: | diff --git a/devel/generate-developer-api-docs b/devel/regenerate-developer-api-docs similarity index 100% rename from devel/generate-developer-api-docs rename to devel/regenerate-developer-api-docs diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index a76ecf2fc..dd9f5750b 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -324,13 +324,13 @@ file in order to render the pages. reStructuredText file should be added under `docs/usage/cli/` in addition to the new file under `docs/api/`. -### Automatically updating developer API docs +### Regenerating developer API docs -To update the developer API documentation after adding or removing an augur submodule, -autogenerate a new API file as follows. +To regenerate the developer API documentation after adding, renaming, or removing an augur +submodule, autogenerate a new API file as follows. ```bash -./devel/generate-developer-api-docs +./devel/regenerate-developer-api-docs ``` ### Building documentation From 070a6394ee100741f68b3cb116a4f991e2b76690 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Wed, 10 Jul 2024 13:52:11 -0700 Subject: [PATCH 4/5] Clarify doc update instructions Update the developer API path and reference the script. --- docs/contribute/DEV_DOCS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md index dd9f5750b..bedfd695e 100644 --- a/docs/contribute/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -319,10 +319,11 @@ 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 From 0f60f36398a34f637eba18756b6b5a0539458916 Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Tue, 9 Jul 2024 10:38:55 -0700 Subject: [PATCH 5/5] Add clarity to docs check error message Reference dev docs and cover all scenarios. --- .github/workflows/ci.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 82ea46e28..92ba7fa4d 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -226,6 +226,7 @@ jobs: 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: " >&2 + echo "If there are changes to the Augur CLI, please manually adjust files under 'docs/usage/cli/'." >&2 exit 1 fi