From e697d78d5a907014252df9aec79d981b800aac91 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 29 Oct 2020 13:31:11 +0100 Subject: [PATCH] [mod] make docs-live - remove --port option from sphinx-autobuild Setting port fixed to 8080 has drawbacks when this port is already in use from another application [1]. Removing this option from the command line offers the use of the sphinx-autobuild defaults which are much more flexible [2]. [1] https://github.com/searx/searx/issues/2282 [2] https://github.com/executablebooks/sphinx-autobuild/blob/master/README.md Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 17 ++++++++++++++++- utils/makefile.sphinx | 2 +- 2 files changed, 17 insertions(+), 2 deletions(-) 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 $@