kopia lustrzana https://github.com/jupyterhub/repo2docker
docs: add devenv and linkcheck
rodzic
b4a1b50984
commit
9559cf2517
|
@ -2,9 +2,9 @@ tasks:
|
||||||
- init: |
|
- init: |
|
||||||
pip3 install sphinx-autobuild
|
pip3 install sphinx-autobuild
|
||||||
pip3 install -r docs/requirements.txt
|
pip3 install -r docs/requirements.txt
|
||||||
pip3 install -e.
|
pip3 install -e .
|
||||||
command: |
|
command: |
|
||||||
sphinx-autobuild docs/source/ docs/build/html/
|
sphinx-autobuild docs/source/ docs/_build/html/
|
||||||
name: Sphinx preview
|
name: Sphinx preview
|
||||||
ports:
|
ports:
|
||||||
- port: 8000
|
- port: 8000
|
||||||
|
|
|
@ -1,20 +1,38 @@
|
||||||
# Minimal makefile for Sphinx documentation
|
# Makefile for Sphinx documentation generated by sphinx-quickstart
|
||||||
#
|
# ----------------------------------------------------------------------------
|
||||||
|
|
||||||
# You can set these variables from the command line.
|
# You can set these variables from the command line, and also
|
||||||
SPHINXOPTS = -W
|
# from the environment for the first two.
|
||||||
SPHINXBUILD = python3 -msphinx
|
SPHINXOPTS ?=
|
||||||
SPHINXPROJ = repo2docker
|
SPHINXBUILD ?= sphinx-build
|
||||||
SOURCEDIR = source
|
SOURCEDIR = source
|
||||||
BUILDDIR = build
|
BUILDDIR = _build
|
||||||
|
|
||||||
# Put it first so that "make" without argument is like "make help".
|
# Put it first so that "make" without argument is like "make help".
|
||||||
help:
|
help:
|
||||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
|
||||||
|
|
||||||
.PHONY: help Makefile
|
.PHONY: help Makefile
|
||||||
|
|
||||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
# 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
|
%: 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."
|
||||||
|
|
|
@ -5,32 +5,51 @@ pushd %~dp0
|
||||||
REM Command file for Sphinx documentation
|
REM Command file for Sphinx documentation
|
||||||
|
|
||||||
if "%SPHINXBUILD%" == "" (
|
if "%SPHINXBUILD%" == "" (
|
||||||
set SPHINXBUILD=python -msphinx
|
set SPHINXBUILD=sphinx-build
|
||||||
)
|
)
|
||||||
set SOURCEDIR=source
|
set SOURCEDIR=source
|
||||||
set BUILDDIR=build
|
set BUILDDIR=_build
|
||||||
set SPHINXPROJ=repo2docker
|
|
||||||
|
|
||||||
if "%1" == "" goto help
|
if "%1" == "" goto help
|
||||||
|
if "%1" == "devenv" goto devenv
|
||||||
|
if "%1" == "linkcheck" goto linkcheck
|
||||||
|
goto default
|
||||||
|
|
||||||
|
|
||||||
|
:default
|
||||||
%SPHINXBUILD% >NUL 2>NUL
|
%SPHINXBUILD% >NUL 2>NUL
|
||||||
if errorlevel 9009 (
|
if errorlevel 9009 (
|
||||||
echo.
|
echo.
|
||||||
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
|
echo.The 'sphinx-build' command was not found. Open and read README.md!
|
||||||
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.
|
|
||||||
echo.If you don't have Sphinx installed, grab it from
|
|
||||||
echo.http://sphinx-doc.org/
|
|
||||||
exit /b 1
|
exit /b 1
|
||||||
)
|
)
|
||||||
|
%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
|
||||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
|
||||||
goto end
|
goto end
|
||||||
|
|
||||||
|
|
||||||
:help
|
:help
|
||||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
|
||||||
|
goto end
|
||||||
|
|
||||||
|
|
||||||
|
:devenv
|
||||||
|
sphinx-autobuild >NUL 2>NUL
|
||||||
|
if errorlevel 9009 (
|
||||||
|
echo.
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
|
: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
|
||||||
|
|
||||||
|
|
||||||
:end
|
:end
|
||||||
popd
|
popd
|
||||||
|
|
|
@ -2,3 +2,4 @@ sphinx==4.0.2
|
||||||
sphinxcontrib-autoprogram==0.1.7
|
sphinxcontrib-autoprogram==0.1.7
|
||||||
pydata-sphinx-theme==0.6.3
|
pydata-sphinx-theme==0.6.3
|
||||||
myst-parser==0.15.2
|
myst-parser==0.15.2
|
||||||
|
sphinx-autobuild
|
||||||
|
|
|
@ -184,13 +184,11 @@ Then you are good to go!
|
||||||
|
|
||||||
## Building the documentation locally
|
## 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
|
```bash
|
||||||
pip install -r docs/requirements.txt
|
pip install -r docs/requirements.txt
|
||||||
|
|
||||||
cd docs/
|
cd docs/
|
||||||
make html
|
make devenv
|
||||||
```
|
```
|
||||||
|
|
||||||
Then open the file `docs/build/html/index.html` in your browser.
|
|
||||||
|
|
Ładowanie…
Reference in New Issue