docs: add devenv and linkcheck
MODIFY
.gitpod.yml
.gitpod.yml
@@ -4,7 +4,7 @@ tasks:
pip3 install -r docs/requirements.txt
pip3 install -e .
command: |
- sphinx-autobuild docs/source/ docs/build/html/
+ sphinx-autobuild docs/source/ docs/_build/html/
name: Sphinx preview
ports:
- port: 8000

MODIFY
docs/Makefile
docs/Makefile
-# Minimal makefile for Sphinx documentation
-#
+# Makefile for Sphinx documentation generated by sphinx-quickstart
+# ----------------------------------------------------------------------------
-# You can set these variables from the command line.
-SPHINXOPTS = -W
-SPHINXBUILD = python3 -msphinx
-SPHINXPROJ = repo2docker
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
-BUILDDIR = build
+BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+# "make mode" option.
%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+
+# Manually added commands
+# ----------------------------------------------------------------------------
+
+# For local development:
+# - builds and rebuilds html on changes to source
+# - starts a livereload enabled webserver and opens up a browser
+devenv:
+ sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# For local development and CI:
+# - verifies that links are valid
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."

MODIFY
docs/make.bat
docs/make.bat
@@ -5,32 +5,51 @@ pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=python -msphinx
+ set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
-set BUILDDIR=build
-set SPHINXPROJ=repo2docker
+set BUILDDIR=_build
if "%1" == "" goto help
+if "%1" == "devenv" goto devenv
+if "%1" == "linkcheck" goto linkcheck
+goto default
+
+:default
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
- echo.The Sphinx module was not found. Make sure you have Sphinx installed,
- echo.then set the SPHINXBUILD environment variable to point to the full
- echo.path of the 'sphinx-build' executable. Alternatively you may add the
- echo.Sphinx directory to PATH.
+ echo.The 'sphinx-build' command was not found. Open and read README.md!
+ exit /b 1
+)
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:help
+%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:devenv
+sphinx-autobuild >NUL 2>NUL
+if errorlevel 9009 (
echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
+ echo.The 'sphinx-autobuild' command was not found. Open and read README.md!
exit /b 1
)
+sphinx-autobuild -b html --open-browser "%SOURCEDIR%" "%BUILDDIR%/html" %SPHINXOPTS%
+goto end
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:linkcheck
+%SPHINXBUILD% -b linkcheck "%SOURCEDIR%" "%BUILDDIR%/linkcheck" %SPHINXOPTS%
+echo.
+echo.Link check complete; look for any errors in the above output
+echo.or in "%BUILDDIR%/linkcheck/output.txt".
goto end
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

MODIFY
docs/requirements.txt
docs/requirements.txt
@@ -2,3 +2,4 @@ sphinx==4.0.2
sphinxcontrib-autoprogram==0.1.7
pydata-sphinx-theme==0.6.3
myst-parser==0.15.2
+sphinx-autobuild

MODIFY
docs/source/contributing/contributing.md
docs/source/contributing/contributing.md
@@ -184,13 +184,11 @@ Then you are good to go!
## Building the documentation locally
-If you only changed the documentation, you can also build the documentation locally using `sphinx` .
+You can build and inspect the result of documentation changes locally.
```bash
pip install -r docs/requirements.txt
cd docs/
-make html
+make devenv
```
-
-Then open the file `docs/build/html/index.html` in your browser.

docs: add devenv and linkcheck