diff --git a/Documentation/Makefile b/Documentation/Makefile index 73575e06ed..f57719d2a4 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -36,6 +36,9 @@ help: html: clean +autobuild: clean + sphinx-autobuild . _build -j=8 + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst index 9b19650208..a430716f16 100644 --- a/Documentation/contributing/documentation.rst +++ b/Documentation/contributing/documentation.rst @@ -39,6 +39,25 @@ go into ``Documentation`` directory. Then, $ xdg-open _build/html/index.html +Live Rebuild +------------ + +For more comfortable editing and previewing of changes (as ``make html`` will perform a slower full rebuild), +you can install ``sphinx-autobuild`` which will monitor file changes and rebuild only affected files. To +install it (within the virtual environment): + +.. code-block:: console + + $ pip3 install sphinx-autobuild + +To run: + +.. code-block:: console + + $ make autobuild + +Which will perform an initial clean build and monitor changes from then on. + Contributing ============ @@ -122,19 +141,10 @@ Linking To generate internal links, Sphinx's `roles `_ should be used. So, use ``:ref:`` instead of standard RST syntax like ```link `_`` for internal links. - -Moreover, sphinx is configured to use `autosectionlabel `_ extension. This means that sections will automatically get a label that can be linked with the -`:ref:`. For example: - -.. code-block:: RST - - This is a Section - ================= - - :ref:`This is a Section` is a link to this very same section. - If the target is in a different file, you can refer it with: ``:ref:`link text ```. +Linking to a specific document can be done with ``:doc:`/path/to/document``` (without ``.rst`` extension). + Notes and TODOS ---------------