167 lines
5.8 KiB
ReStructuredText
167 lines
5.8 KiB
ReStructuredText
=============
|
|
Documentation
|
|
=============
|
|
|
|
The Apache NuttX Documentation is built using the
|
|
`Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`_. Documentation
|
|
is written in `ReStructured Text <https://docutils.sourceforge.io/rst.html>`_ (RST),
|
|
with Sphinx-specific directives. RST is the format used for
|
|
`Python documentation <https://docs.python.org/3/>`_ and is also used in many other projects.
|
|
Using Sphinx, the RST files are rendered into HTML files that can be read in your browser.
|
|
|
|
Building
|
|
========
|
|
|
|
To render the Documentation locally, you should clone the NuttX main repository, and
|
|
go into ``Documentation`` directory. Then,
|
|
|
|
1. Install Sphinx and other dependencies using pipenv.
|
|
You may also find it helpful on platforms such as Windows and MacOS to use *pyenv*
|
|
to manage your python installation. You can read about installing that on the
|
|
project `site <https://github.com/pyenv/pyenv#installation>`_.
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install pipenv
|
|
$ pipenv install
|
|
$ # activate the virtual environent
|
|
$ pipenv shell
|
|
|
|
2. Build documentation:
|
|
|
|
.. code-block:: console
|
|
|
|
$ make html
|
|
|
|
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>```.
|
|
|
|
Notes and TODOS
|
|
---------------
|
|
|
|
Use RST `admonitions <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`_ to highlight things from the text,
|
|
such as a note that should be prominently displayed.
|
|
|
|
In case you need to leave a TODO note in the documentation to point that something needs to be improved, use a ``todo`` admonition,
|
|
which is available via the ``sphinx.ext.todo`` extension. This will let the reader of the documentation also know that the documentation
|
|
is not yet finished somewhere and may further motivate a contribution.
|
|
|
|
Tips
|
|
====
|
|
|
|
Spacing
|
|
-------
|
|
|
|
If you are getting formatting errors, be sure to provide the appropiate spacing between a directive and its content.
|
|
Generally, you should follow this format:
|
|
|
|
.. code-block:: RST
|
|
|
|
.. directive::
|
|
|
|
child content
|
|
|
|
non-child content which appears after previous directive
|
|
|
|
Note the line between directive and content and the indentation.
|
|
|