mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-02 22:51:14 +00:00
Backport changes made in 6147 to release/4.0
This commit is contained in:
liying
@@ -1,7 +1,7 @@
|
||||
Documenting Code
|
||||
================
|
||||
|
||||
The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation.
|
||||
The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation.
|
||||
|
||||
|
||||
Introduction
|
||||
@@ -20,14 +20,14 @@ Typical comment block, that contains documentation of a function, looks like bel
|
||||
.. image:: ../../_static/doc-code-documentation-inline.png
|
||||
:align: center
|
||||
:alt: Sample inline code documentation
|
||||
|
||||
Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data reach and very well organized `Doxygen Manual <https://www.stack.nl/~dimitri/doxygen/manual/index.html>`_.
|
||||
|
||||
Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data rich and very well organized `Doxygen Manual <https://www.stack.nl/~dimitri/doxygen/manual/index.html>`_.
|
||||
|
||||
|
||||
Why we need it?
|
||||
---------------
|
||||
|
||||
The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx <http://www.sphinx-doc.org/>`_ and `Breathe <https://breathe.readthedocs.io/>`_ to aid preparation and automatic updates of API documentation when the code changes.
|
||||
The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx <http://www.sphinx-doc.org/>`_ and `Breathe <https://breathe.readthedocs.io/>`_ to aid preparation and automatic updates of API documentation when the code changes.
|
||||
|
||||
With these tools the above piece of code renders like below:
|
||||
|
||||
@@ -56,7 +56,7 @@ When writing code for this repository, please follow guidelines below.
|
||||
.. image:: ../../_static/doc-code-void-function.png
|
||||
:align: center
|
||||
:alt: Sample void function documented inline and after rendering
|
||||
|
||||
|
||||
5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
|
||||
|
||||
.. image:: ../../_static/doc-code-member.png
|
||||
@@ -73,7 +73,7 @@ When writing code for this repository, please follow guidelines below.
|
||||
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
|
||||
* - other error codes from the underlying storage driver
|
||||
*
|
||||
|
||||
|
||||
7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``.
|
||||
|
||||
|
||||
@@ -116,7 +116,7 @@ There is couple of tips, how you can make your documentation even better and mor
|
||||
*/
|
||||
void first_similar_function (void);
|
||||
void second_similar_function (void);
|
||||
/**@}*/
|
||||
/**@}*/
|
||||
|
||||
For practical example see :component_file:`nvs_flash/include/nvs.h`.
|
||||
|
||||
@@ -132,14 +132,14 @@ There is couple of tips, how you can make your documentation even better and mor
|
||||
|
||||
Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
|
||||
|
||||
6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory.
|
||||
6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory.
|
||||
|
||||
.. _link-custom-roles:
|
||||
|
||||
Linking Examples
|
||||
----------------
|
||||
|
||||
When linking to examples on GitHub do not use absolute / hadcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted.
|
||||
When linking to examples on GitHub do not use absolute / hardcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted.
|
||||
|
||||
The following roles are provided:
|
||||
|
||||
@@ -197,9 +197,9 @@ The following types of diagrams are supported:
|
||||
* `Activity diagram <http://blockdiag.com/en/actdiag/index.html>`_
|
||||
* `Logical network diagram <http://blockdiag.com/en/nwdiag/index.html>`_
|
||||
|
||||
With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents.
|
||||
With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents.
|
||||
|
||||
For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image.
|
||||
For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image.
|
||||
|
||||
Below are couple of diagram examples:
|
||||
|
||||
@@ -215,6 +215,34 @@ Try them out by modifying the source code and see the diagram instantly renderin
|
||||
There may be slight differences in rendering of font used by the `interactive shell`_ compared to the font used in the esp-idf documentation.
|
||||
|
||||
|
||||
Add Notes
|
||||
---------
|
||||
|
||||
Working on a document, you might need to:
|
||||
|
||||
- Place some suggestions on what should be added or modified in future.
|
||||
- Leave a reminder for yourself or somebody else to follow up.
|
||||
|
||||
In this case, add a todo note to your reST file using the directive ``.. todo::``. For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. todo::
|
||||
|
||||
Add a package diagram.
|
||||
|
||||
If you add ``.. todolist::`` to a reST file, the directive will be replaced by a list of all todo notes from the whole documentation.
|
||||
|
||||
By default, the directives ``.. todo::`` and ``.. todolist::`` are ignored by documentation builders. If you want the notes and the list of notes to be visible in your locally built documentation, do the following:
|
||||
|
||||
1. Open your local ``conf_common.py`` file.
|
||||
2. Find the parameter ``todo_include_todos``.
|
||||
3. Change its value from ``False`` to ``True``.
|
||||
|
||||
Before pushing your changes to origin, please set the value of ``todo_include_todos`` back to ``False``.
|
||||
|
||||
For more details about the extension, see `sphinx.ext.todo <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todolist>`_ documentation.
|
||||
|
||||
Put it all together
|
||||
-------------------
|
||||
|
||||
@@ -231,10 +259,10 @@ OK, but I am new to Sphinx!
|
||||
3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so:
|
||||
|
||||
* Install `Sphinx <http://www.sphinx-doc.org/>`_, `Breathe <https://breathe.readthedocs.io/>`_, `Blockdiag <http://blockdiag.com/en/index.html>`_ and `Doxygen <https://www.stack.nl/~dimitri/doxygen/>`_ to build it locally, see chapter below.
|
||||
|
||||
|
||||
* Set up an account on `Read the Docs <https://readthedocs.org/>`_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great.
|
||||
|
||||
4. To preview documentation before building, use `Sublime Text <https://www.sublimetext.com/>`_ editor together with `OmniMarkupPreviewer <https://github.com/timonwong/OmniMarkupPreviewer>`_ plugin.
|
||||
4. To preview documentation before building, use `Sublime Text <https://www.sublimetext.com/>`_ editor together with `OmniMarkupPreviewer <https://github.com/timonwong/OmniMarkupPreviewer>`_ plugin.
|
||||
|
||||
|
||||
.. _setup-for-building-documentation:
|
||||
@@ -242,6 +270,9 @@ OK, but I am new to Sphinx!
|
||||
Setup for building documentation locally
|
||||
----------------------------------------
|
||||
|
||||
Install Dependencies
|
||||
""""""""""""""""""""
|
||||
|
||||
You can setup environment to build documentation locally on your PC by installing:
|
||||
|
||||
1. Doxygen - https://www.stack.nl/~dimitri/doxygen/
|
||||
@@ -254,6 +285,7 @@ You can setup environment to build documentation locally on your PC by installin
|
||||
|
||||
The package "sphinx_rtd_theme" is added to have the same "look and feel" of `ESP32 Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/index.html>`_ documentation like on the "Read the Docs" hosting site.
|
||||
|
||||
|
||||
Do not worry about being confronted with several packages to install. Besides Doxygen, all remaining packages are written in Python. Therefore installation of all of them is combined into one simple step.
|
||||
|
||||
Installation of Doxygen is OS dependent:
|
||||
@@ -278,7 +310,7 @@ Installation of Doxygen is OS dependent:
|
||||
|
||||
.. note::
|
||||
|
||||
If you are installing on Windows system (Linux and MacOS users should skip this note), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`.
|
||||
If you are installing on Windows MSYS2 system (Linux and MacOS users should skip this note, Windows users who don't use MSYS2 will need to find other alternatives), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`.
|
||||
|
||||
1. Update all the system packages:
|
||||
|
||||
@@ -317,13 +349,12 @@ Now you should be ready to build documentation by invoking::
|
||||
|
||||
make html
|
||||
|
||||
This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser.
|
||||
|
||||
This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser.
|
||||
|
||||
Wrap up
|
||||
-------
|
||||
|
||||
We love good code that is doing cool things.
|
||||
We love good code that is doing cool things.
|
||||
We love it even better, if it is well documented, so we can quickly make it run and also do the cool things.
|
||||
|
||||
Go ahead, contribute your code and documentation!
|
||||
|
||||
Reference in New Issue
Block a user