From 5b757f6c8457997b7a38964ac6858144f16a71ae Mon Sep 17 00:00:00 2001 From: Valentin Pratz Date: Tue, 1 Apr 2025 15:19:41 +0000 Subject: [PATCH] [no ci] docs: more explicit make command names There was some confusion arising from the fact that `make docs` did not build the local docs. To avoid this confusion in the future, the naming is made more explicit with the following changes: make local -> make local-docs make docs -> make production-docs make docs-sequential -> make production-docs-sequential The documentation and the GitHub actions are adapted as well. --- .github/workflows/multiversion-docs.yaml | 2 +- .github/workflows/test-docs.yaml | 2 +- CONTRIBUTING.md | 6 +++--- docsrc/Makefile | 12 ++++++------ docsrc/README.md | 8 ++++---- docsrc/make.bat | 10 +++++----- 6 files changed, 20 insertions(+), 20 deletions(-) diff --git a/.github/workflows/multiversion-docs.yaml b/.github/workflows/multiversion-docs.yaml index 4bcf7897c..077e6e963 100644 --- a/.github/workflows/multiversion-docs.yaml +++ b/.github/workflows/multiversion-docs.yaml @@ -43,7 +43,7 @@ jobs: run: | cd ./repo/docsrc make clean - make docs-sequential + make production-docs-sequential - name: Checkout gh-pages-dev uses: actions/checkout@v3 diff --git a/.github/workflows/test-docs.yaml b/.github/workflows/test-docs.yaml index 59c56db6b..2b58f1db4 100644 --- a/.github/workflows/test-docs.yaml +++ b/.github/workflows/test-docs.yaml @@ -31,7 +31,7 @@ jobs: run: | cd ./docsrc make clean - make local + make local-docs - name: Clean up run: | cd ./docsrc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7db7f42e2..caba5dc59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -171,17 +171,17 @@ You can re-build the for your local state with: ```bash cd docsrc -make clean && make local +make clean && make local-docs # in case of issues, try `make clean-all` ``` Note that files ignored by git (i.e., listed in `.gitignore`) are not included in the documentation. -We also provide a multi-version documentation. To generate it, run +We also provide a multi-version documentation, which renders the branches `main` and `stable-legacy`. To generate it, run ```bash cd docsrc -make clean && make docs +make clean && make production-docs ``` This will create and cache virtual environments for the build at `docsrc/.docs_venvs`. diff --git a/docsrc/Makefile b/docsrc/Makefile index a715f40c6..f6bdfa66c 100644 --- a/docsrc/Makefile +++ b/docsrc/Makefile @@ -1,5 +1,5 @@ -.PHONY: docs-sequential -docs-sequential: +.PHONY: production-docs-sequential +production-docs-sequential: @sphinx-polyversion --sequential poly.py @echo 'Copying docs to ../docs' @rm -rf ../docs/* @@ -7,8 +7,8 @@ docs-sequential: @cp .nojekyll ../docs/.nojekyll @rm -rf _build_polyversion -.PHONY: docs -docs: +.PHONY: production-docs +production-docs: @sphinx-polyversion poly.py @echo 'Copying docs to ../docs' @rm -rf ../docs/* @@ -16,8 +16,8 @@ docs: @cp .nojekyll ../docs/.nojekyll @rm -rf _build_polyversion -.PHONY: local -local: +.PHONY: local-docs +local-docs: @sphinx-polyversion --local poly.py @echo 'Copying docs to ../docs' @rm -rf ../docs/* diff --git a/docsrc/README.md b/docsrc/README.md index 0b304e8c4..d35d7701e 100644 --- a/docsrc/README.md +++ b/docsrc/README.md @@ -5,9 +5,9 @@ To install the necessary dependencies, please run `pip install -e .[docs]` in the root directory. You can then do the following (inside the `docsrc` directory): -1. `make local`: Generate the docs for the current local state -2. `make docs`: Build the docs for branches and tags specified in `poly.py` in sequential fashion. Virtual environments are cached (run `make clean-all` to delete) -3. `make docs-sequential`: As `make docs`, but versions are built sequentially, and the build environment is deleted after each build (see below for details) +1. `make local-docs`: Generate the docs for the current local state +2. `make production-docs`: Build the docs for branches and tags specified in `poly.py` in a parallel fashion. Virtual environments are cached (run `make clean-all` to delete) +3. `make production-docs-sequential`: As `make production-docs`, but versions are built sequentially, and the build environment is deleted after each build (see below for details) 4. `make view-docs`: Starts a local webserver to display the content of `../docs` The docs will be copied to `../docs`. @@ -69,7 +69,7 @@ By setting the `--sequential` flag in the `sphinx-polyversion` call, a resource-constrained approach is chosen. Builds are sequential, and the virtual environment is deleted after the build. This overcomes the disk space limitations in the GitHub actions, at the cost of slightly higher built times. -This is used in `make docs-sequential`. +This is used in `make production-docs-sequential`. ### Internals diff --git a/docsrc/make.bat b/docsrc/make.bat index 91f09fdcf..1464fe82f 100644 --- a/docsrc/make.bat +++ b/docsrc/make.bat @@ -8,18 +8,18 @@ echo.Warning: This make.bat was not tested. If you encounter errors, please echo.refer to Makefile and open an issue. if "%1" == "" goto help -if "%1" == "docs" goto docs -if "%1" == "docs-sequential" goto docssequential -if "%1" == "local" goto local +if "%1" == "production-docs" goto docs +if "%1" == "production-docs-sequential" goto docssequential +if "%1" == "local-docs" goto localdocs if "%1" == "clean" goto clean if "%1" == "clean-all" goto cleanall if "%1" == "view-docs" goto viewdocs :help -echo.Please specify a command (local, docs, docs-sequential, clean, clean-all) +echo.Please specify a command (local-docs, production-docs, production-docs-sequential, clean, clean-all) goto end -:docssequential +:localdocs sphinx-polyversion --local poly.py echo.Copying docs to ../docs del /q /s ..\docs\*