[incubator-nuttx] 02/03: doc: mention sphinx-autobuild in contributing section

[xi...@apache.org]

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 <ma...@protobits.dev>
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
 ---------------