This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 33aafe8e7f66efc599e32ac7961f69fb7197bfcd Author: Matias N <[email protected]> AuthorDate: Fri Mar 26 14:48:22 2021 -0300 doc: mention sphinx-autobuild in contributing section --- Documentation/Makefile | 3 +++ Documentation/contributing/documentation.rst | 32 ++++++++++++++++++---------- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 73575e0..f57719d 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 9b19650..a430716 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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ should be used. So, use ``:ref:`` instead of standard RST syntax like ```link <target>`_`` for internal links. - -Moreover, sphinx is configured to use `autosectionlabel <https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document>`_ 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 </pathtorst:Section Name>```. +Linking to a specific document can be done with ``:doc:`/path/to/document``` (without ``.rst`` extension). + Notes and TODOS ---------------
