[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.

Author: vpratz

.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

.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

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`.

docsrc/Makefile

@@ -1,23 +1,23 @@
-.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/*
 	@cp -a _build_polyversion/. ../docs
 	@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/*
 	@cp -a _build_polyversion/. ../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/*

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
 

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