diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b3c47dd..e652b4fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -249,6 +249,14 @@ Alternatively, to automatically rebuild the docs when changes occur, you can inv nox -s autobuild ``` +By default, this serves docs on port ``8000`` and opens your default browser. +You can customize this behavior with environment variables: + +```shell +SPYDER_DOCS_AUTOBUILD_PORT=8765 nox -s autobuild +SPYDER_DOCS_AUTOBUILD_OPEN_BROWSER=0 nox -s autobuild +``` + You can also pass your own custom [Sphinx build options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) after a ``--`` separator which are added to the default set. For example, to rebuild just the install guide and FAQ in verbose mode with the ``dirhtml`` builder (our noxfile automatically prepends the source directory for you, so typing the full relative path is optional): diff --git a/noxfile.py b/noxfile.py index 5c8518cf..524fff44 100644 --- a/noxfile.py +++ b/noxfile.py @@ -46,6 +46,9 @@ SERVE_IP = "127.0.0.1" SERVE_PORT = 5000 +AUTOBUILD_PORT = 8000 +AUTOBUILD_PORT_ENV_VAR = "SPYDER_DOCS_AUTOBUILD_PORT" +AUTOBUILD_OPEN_BROWSER_ENV_VAR = "SPYDER_DOCS_AUTOBUILD_OPEN_BROWSER" LINT_INVOCATION = ("prek",) @@ -130,6 +133,14 @@ def process_filenames(filenames, source_dir=SOURCE_DIR): return filenames +def env_var_to_bool(var_name, *, default): + """Convert an environment variable to bool with common false values.""" + value = os.environ.get(var_name) + if value is None: + return default + return value.strip().lower() not in {"0", "false", "no", "off"} + + def extract_option_values(options, option_names, *, split_csv=False): """Extract particular option values from a sequence of options.""" option_values = [] @@ -431,17 +442,26 @@ def _autodocs(session): """Use Sphinx-Autobuild to rebuild the project and open in browser.""" session.install("sphinx-autobuild") + autobuild_port = os.environ.get( + AUTOBUILD_PORT_ENV_VAR, str(AUTOBUILD_PORT) + ) + open_browser = env_var_to_bool( + AUTOBUILD_OPEN_BROWSER_ENV_VAR, default=True + ) + autobuild_invocation = [ + "sphinx-autobuild", + f"--port={autobuild_port}", + f"--watch={SOURCE_DIR}", + ] + if open_browser: + autobuild_invocation.append("--open-browser") + with tempfile.TemporaryDirectory() as destination: sphinx_invocation = construct_sphinx_invocation( posargs=session.posargs[1:], build_dir=destination, extra_options=["-a"], - build_invocation=[ - "sphinx-autobuild", - "--port=0", - f"--watch={SOURCE_DIR}", - "--open-browser", - ], + build_invocation=autobuild_invocation, ) session.run(*sphinx_invocation)