From 3f723a247d49099595d0bb9756277259f56deb8a Mon Sep 17 00:00:00 2001 From: Matias N Date: Sat, 15 Aug 2020 22:28:02 -0300 Subject: [PATCH] add basic documentation contributing guidelines --- Documentation/contributing/documentation.rst | 268 ++++++++++--------- 1 file changed, 139 insertions(+), 129 deletions(-) diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst index 0e2e90d28b2..de92c16b5b7 100644 --- a/Documentation/contributing/documentation.rst +++ b/Documentation/contributing/documentation.rst @@ -1,170 +1,180 @@ -.. include:: /substitutions.rst - -.. note:: This is a first version of the document, will be updated once new documentation - system is in place. - +============= Documentation ============= -The Apache NuttX Documentation is made using the -`Sphinx documentation system `_. Sphinx documentation -is written in `ReStructured Text `_ (RST). RST is -the format used for `Python documentation `_ and is also used -in many other projects. +The Apache NuttX Documentation is built using the +`Sphinx documentation system `_. Documentation +is written in `ReStructured Text `_ (RST), +with Sphinx-specific directives. RST is the format used for +`Python documentation `_ 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. -Contributions and fixes to the Apache NuttX Companion are encouraged and welcome. Here's how to do -it. +Building +======== -#. Fork the Apache NuttX Documentation Repository +To render the Documentation locally, you should clone the NuttX main repository, and +go into ``Documentation`` directory. Then, - Visit this link and hit the Fork button in the upper right of the page: + 1. Install sphinx and other dependencies. You can do this in one of two ways: + + * **Fast and easy**: + + .. code-block:: console + + pip3 install -r requirements.txt + + * **Slower but cleaner**: + + .. code-block:: console - * `NuttX (v01d's fork) `_ + $ # install pyenv + $ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash + $ # install python + $ pyenv install 3.7.3 + $ pyenv local 3.7.3 + $ # install pipenv + $ pip install pipenv + $ # install sphinx and related software + $ pipenv install + $ # activate the virtual environent + $ pipenv shell + + .. todo:: check that Pipfile.lock is up to date w.r.t. requirements.txt + + 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 - |br| +Contributing +============ -#. Clone the Forked Repository +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. - Click the "Clone or Download" button and copy the clone URL. Then do this: +The contribution workflow is the same as for the code, so check the :doc:`/contributing/workflow` to understand +how your changes should be upstreamed. - .. code-block:: bash +Writing ReStructure Text with Sphinx +==================================== - $ git clone +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.): -#. Install Sphinx + * `Sphinx documentation system `__ + * `ReStructured Text documentation `__ + * `Sphinx Guide to ReStructured Text `__ + * `Restructured Text cheat sheet `__ - On the command line, change directories to the newly-downloaded repository directory: +Documentation Conventions +========================= - .. code-block:: bash +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. - $ cd incubator-nuttx - $ # install pyenv - $ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash - $ # install python - $ pyenv install 3.7.3 - $ pyenv local 3.7.3 - $ # install pipenv - $ pip install pipenv - $ # install sphinx and related software - $ pipenv install - $ # activate the virtual environent - $ pipenv shell +Indentation +----------- -#. Build the HTML Documentation Locally +Child blocks should be indented two-spaces. This includes itemizations/enumerations. - .. code-block:: bash +Headings +-------- - $ cd docs - $ make html - Running Sphinx v2.4.1 - making output directory... done - building [mo]: targets for 0 po files that are out of date - building [html]: targets for 12 source files that are out of date - updating environment: [new config] 12 added, 0 changed, 0 removed - reading sources... [100%] user/simulator - looking for now-outdated files... none found - pickling environment... done - checking consistency... done - preparing documents... done - writing output... [100%] user/simulator - generating indices... genindexdone - writing additional pages... searchdone - copying static files... ... done - copying extra files... done - dumping search index in English (code: en)... done - dumping object inventory... done - build succeeded. +Three levels of headings should be used in general. The style used to mark sections is based around ``=`` and ``-``. +Sections should look like this: - The HTML pages are in ``_build/html``. +.. code-block:: RST -#. Check Out a New Branch + ================= + Top Level Heading + ================= - .. code-block:: bash + Subsection + ========== + + Subsubsection + ------------- + +Code +---- - $ git checkout -b feature/my-branch +Code should be documented using the `C domain `_. +This means for example that a function should be documented as: -#. Make Your Changes +.. code-block:: RST - .. code-block:: bash + .. 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 `_, 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: - $ vim user/intro.rst # or use the editor of your choice - # on whatever file you want to change +.. code-block:: RST -#. Rebuild the HTML Documentation + The text file should have the following content:: + + Line1 + Line2 + Line3 - .. code-block:: bash +Linking +------- - $ make html +To generate internal links, Sphinx's `roles `_ should +be used. So, use ``:ref:`` instead of standard RST syntax like ```link `_`` for internal links. -#. View the Documentation in a Web Browser +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: - You can open the file ``docs/_build/html/index.html``. - |br| - |br| +.. code-block:: RST -#. Iterate + 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 ```. - Repeat Steps 6, 7, and 8 until you're happy with the result. - |br| - |br| +Notes and TODOS +--------------- -#. Commit the Changes +Use RST `admonitions `_ to highlight things from the text, +such as a note that should be prominently displayed. - .. code-block:: bash +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. - $ git add introduction/main.rst # or whatever files you changed - $ git commit +Tips +==== -#. Push to Your Branch +Spacing +------- - .. code-block:: bash +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: - $ git push +.. code-block:: RST -#. Submit Your Pull Request - - Go to the `Apache NuttX (v01d's fork) `_ page - on Github and click the "Pull Request" button. See Github's `Creating a Pull Request - `__ - page for more info. - - Use this template for the Pull Request description text: - - :: - - ### Summary - ### Impact - ### Limitations / TODO - ### Detail - ### Testing - ### How To Verify - - Fill out the sections describing your changes. The summary should be a concise bulleted - list. - - The ``How To Verify`` section is only needed if you change how the project is built or - add some other programs or scripts. - |br| - |br| - -#. Make Changes If Requested - - When you submit your Pull Request, the Apache NuttX Documentation team will review the changes, - and may request that you modify your submission. Please work with them to get your - changes accepted. - |br| - |br| - -#. You're Done! - - Feel good that you've made Apache NuttX documentation better for yourself and others. You've - just made the world a better place! - -Sphinx Resources ----------------- - -* `Sphinx documentation system `__ -* `ReStructured Text documentation `__ -* `Sphinx Guide to ReStructured Text `__ -* `Restructured Text cheat sheet `__ + .. directive:: + + child content + + non-child content which appears after previous directive + +Note the line between directive and content and the indentation.