The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with:
..code-block:: console
$ xdg-open _build/html/index.html
Contributing
============
Contributions to documentation are appreciated. These can be as simple as fixing a typo or formatting issues to more involved
changes such as documenting parts of NuttX which are not yet covered or even writing guides for other users.
The contribution workflow is the same as for the code, so check the :doc:`/contributing/workflow` to understand
how your changes should be upstreamed.
Writing ReStructure Text with Sphinx
====================================
The following links can be used to learn about RST syntax and about Sphinx specific directives. Note that
sometimes Sphinx's approach is used over standard RST since it is more powerful (e.g. standard linking vs Sphinx
``:ref:`` which can be used across files, ``code-block`` directive vs ``::`` which allows specifying highlight language, etc.):
*`Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`__
*`ReStructured Text documentation <https://docutils.sourceforge.io/rst.html>`__
*`Sphinx Guide to ReStructured Text <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
*`Restructured Text cheat sheet <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
Documentation Conventions
=========================
While RST/Sphinx provide many ways to do things, it is best to follow a given convention to mantain consistency and avoid
pitfalls. For this reason, documentation changes should follow the following set of conventions.
Indentation
-----------
Child blocks should be indented two-spaces. This includes itemizations/enumerations.
Headings
--------
Three levels of headings should be used in general. The style used to mark sections is based around ``=`` and ``-``.
Sections should look like this:
..code-block:: RST
=================
Top Level Heading
=================
Subsection
==========
Subsubsection
-------------
Code
----
Code should be documented using the `C domain <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_.
This means for example that a function should be documented as:
..code-block:: RST
..c:function:: bool myfunction(int arg1, int arg2)
Here the function should be described
:param arg1:Description of arg1
:param arg2:Description of arg2
:return:Description of return value
To document a piece of code, use a ``code-block```directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_, specifying the highlight language. If the block is not of code but some verbatim piece of text,
it is acceptable to use RST standard `::`. This is specially useful and compact when used in the following mode:
..code-block:: RST
The text file should have the following content::
Line1
Line2
Line3
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>```.