From 198768a1c76725d14e6ac608b11cf49d5fbfaeec Mon Sep 17 00:00:00 2001 From: Johannes Altmanninger Date: Sun, 30 Nov 2025 06:24:39 +0100 Subject: [PATCH] CONTRIBUTING: remove -n from sphinx-build, add cmake target The -n flag adds warnings about preexisting problems because we don't check it in CI, so let's not recommend that. Not everyone uses cmake but it's still the source of truth for docs, so mention the cmake incantation. Though it seems like the direct sphinx-build invocation works just fine, so keep it first. --- CONTRIBUTING.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9c65c6ade..7f4c58403 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -89,11 +89,18 @@ Contributing documentation The documentation is stored in ``doc_src/``, and written in ReStructured Text and built with Sphinx. -To build it locally, run from the main fish-shell directory:: +To build it locally, run either:: - sphinx-build -j 8 -b html -n doc_src/ /tmp/fish-doc/ + sphinx-build -j auto -b html doc_src/ /tmp/fish-doc/ -which will build the docs as html in /tmp/fish-doc. You can open it in a browser and see that it looks okay. +which will output HTML docs to /tmp/fish-doc. +You can open it in a browser and see that it looks okay. + +Alternatively, you can use:: + + cmake --build build -t sphinx-docs + +which outputs to build/user_doc/html/. The builtins and various functions shipped with fish are documented in doc_src/cmds/.