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\*