diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 5012dea21..26f8d2bb7 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -141,6 +141,9 @@ Here is an example which makes a complete rebuild: live build ---------- +.. _sphinx-autobuild: + https://github.com/executablebooks/sphinx-autobuild/blob/master/README.md + .. sidebar:: docs-clean It is recommended to assert a complete rebuild before deploying (use @@ -156,9 +159,21 @@ changed. $ make docs-live ... The HTML pages are in dist/docs. - ... Serving on http://0.0.0.0:8080 + ... Serving on http://0.0.0.0:8000 ... Start watching changes +Live builds are implemented by sphinx-autobuild_. Use environment +``$(SPHINXOPTS)`` to pass arguments to the sphinx-autobuild_ command. Except +option ``--host`` (which is always set to ``0.0.0.0``) you can pass any +argument. E.g to find and use a free port, use: + +.. code:: sh + + $ SPHINXOPTS="--port 0" make docs-live + ... + ... Serving on http://0.0.0.0:50593 + ... + .. _deploy on github.io: diff --git a/utils/makefile.sphinx b/utils/makefile.sphinx index ba18dffa6..b4f298d50 100644 --- a/utils/makefile.sphinx +++ b/utils/makefile.sphinx @@ -79,7 +79,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5) -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5 quiet_cmd_sphinx_autobuild = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5) - cmd_sphinx_autobuild = PATH="$(PY_ENV_BIN):$(PATH)" $(PY_ENV_BIN)/sphinx-autobuild $(SPHINX_VERBOSE) --open-browser --host 0.0.0.0 --port 8080 $(SPHINXOPTS)\ + cmd_sphinx_autobuild = PATH="$(PY_ENV_BIN):$(PATH)" $(PY_ENV_BIN)/sphinx-autobuild $(SPHINX_VERBOSE) --open-browser --host 0.0.0.0 $(SPHINXOPTS)\ -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5 quiet_cmd_sphinx_clean = CLEAN $@