mirror of
https://github.com/apache/nuttx.git
synced 2026-05-28 11:56:10 +08:00
Documentation: Remove all tail spaces from *.rst and *.html
by the below command:
find . -type f -name '*.rst' -exec sed --in-place 's/[[:space:]]\+$//' {} \+
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
This commit is contained in:
committed by
Brennan Ashton
parent
a066186127
commit
598e3eedb4
@@ -12,32 +12,32 @@ Using Sphinx, the RST files are rendered into HTML files that can be read in you
|
||||
Building
|
||||
========
|
||||
|
||||
To render the Documentation locally, you should clone the NuttX main repository, and
|
||||
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
|
||||
|
||||
$ xdg-open _build/html/index.html
|
||||
|
||||
Contributing
|
||||
============
|
||||
@@ -85,35 +85,35 @@ Sections should look like this:
|
||||
|
||||
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>`_.
|
||||
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
|
||||
|
||||
Line1
|
||||
Line2
|
||||
Line3
|
||||
|
||||
@@ -124,15 +124,15 @@ To generate internal links, Sphinx's `roles <https://www.sphinx-doc.org/en/maste
|
||||
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:
|
||||
`: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
|
||||
@@ -176,10 +176,10 @@ 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.
|
||||
|
||||
child content
|
||||
|
||||
non-child content which appears after previous directive
|
||||
|
||||
Note the line between directive and content and the indentation.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features)
|
||||
In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features)
|
||||
and documentation (the one you are reading now):
|
||||
|
||||
.. toctree::
|
||||
|
||||
@@ -11,32 +11,32 @@ You should be aware of the following:
|
||||
- All contributions must adhere to the :doc:`Coding Standard <coding_style>`. You can check your files using ``nxstyle``
|
||||
or complete patchsets using ``checkpatch`` script (both found in ``tools`` subdirectory of NuttX repository). This check will also run
|
||||
automatically during CI to ensure conformance.
|
||||
|
||||
|
||||
Note that not all existing files in the repository are already adapted to conform to the standard as this is an ongoing effort. Thus,
|
||||
if you're submitting a patch to an existing file you may have to make the file conform to the standard, even if you are not reponsible
|
||||
for those standard violations.
|
||||
|
||||
for those standard violations.
|
||||
|
||||
It is also appreciated that you separate any styling fixes in a separate commit from the functional changes so that these are more
|
||||
easily readable during review.
|
||||
|
||||
|
||||
- Before starting work on any given non trivial contribution, do subscribe to the mailing list and ask about your idea to avoid
|
||||
wasted effort by going the wrong-route.
|
||||
|
||||
|
||||
- If you are submitting an original contribution (you wrote the code yourself from scratch) it will have to be submitted under
|
||||
the terms of the Apache 2.0 License using the corresponding :ref:`header <contributing/coding_style:Appendix>`.
|
||||
|
||||
|
||||
Note that if you are working as an employee in a company, usually copyright belongs to the company and thus this means the company
|
||||
will have to authorize this and submit the appropriate license agreements.
|
||||
|
||||
|
||||
- If you are submitting third-party code:
|
||||
|
||||
- Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that
|
||||
|
||||
- Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that
|
||||
changes required in third-party code for NuttX support are to be implemented in these projects. As an intermediate solution,
|
||||
it is acceptable to include a patch to be applied to this third-party code, which will be pulled during built.
|
||||
|
||||
|
||||
- If this is from an inactive project, it may be considered for inclusion in NuttX, provided that licensing terms allow to do so
|
||||
and it is deemed of sufficient value to be included, considering that this code will have to be maintained in NuttX afterwards.
|
||||
|
||||
|
||||
Note that it is undesireable to included non Apache 2.0 Licensed code inside the repository, even if the license itself allows it
|
||||
(for example BSD License).
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user