Note
INSTRUCTIONS
- Use this file (:idf_file:`docs/api-reference/template.rst`) as a template to document API.
- Change the file name to the name of the header file that represents documented API.
Include respective files with descriptions from the API folder using
..include::
- README.rst
- example.rst
- ...
- Optionally provide description right in this file.
- Once done, remove all instructions like this one and any superfluous headers.
Note
INSTRUCTIONS
- Provide overview where and how this API may be used.
- Where applicable include code snippets to illustrate functionality of particular functions.
To distinguish between sections, use the following heading levels:
#
with overline, for parts*
with overline, for chapters=
, for sections-
, for subsections^
, for subsubsections"
, for paragraphs
Note
INSTRUCTIONS
- Prepare one or more practical examples to demonstrate functionality of this API.
- Each example should follow pattern of projects located in
esp-idf/examples/
folder. - Place example in this folder complete with
README.md
file. - Provide overview of demonstrated functionality in
README.md
. - With good overview reader should be able to understand what example does without opening the source code.
- Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
- Include flow diagram and screenshots of application output if applicable.
- Finally add in this section synopsis of each example together with link to respective folder in
esp-idf/examples/
.
none
Note
INSTRUCTIONS
- This repository provides for automatic update of API reference documentation using
code markup retrieved by Doxygen from header files <../contribute/documenting-code>
. - Update is done on each documentation build by invoking script :idf_file:`docs/gen-dxd.py for all header files listed in the INPUT statement of :idf_file:`docs/Doxyfile.
Each line of the
INPUT
statement (other than a comment that begins with##
) contains a path to header file*.h
that will be used to generate corresponding*.inc
files:## ## Wi-Fi - API Reference ## ../components/esp32/include/esp_wifi.h \ ../components/esp32/include/esp_smartconfig.h \
- The
*.inc
files contain formatted reference of API members generated automatically on each documentation build. All*.inc
files are placed in Sphinx_build
directory. To see directives generated for e.g.esp_wifi.h
, runpython gen-dxd.py esp32/include/esp_wifi.h
. To show contents of
*.inc
file in documentation, include it as follows:.. include:: /_build/inc/esp_wifi.inc
For example see :idf_file:`docs/en/api-reference/wifi/esp_wifi.rst`
Optionally, rather that using
*.inc
files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp-cmake.rst` for example.Below is the list of common
.. doxygen...::
directives:- Functions -
.. doxygenfunction:: name_of_function
- Unions -
.. doxygenunion:: name_of_union
- Structures -
.. doxygenstruct:: name_of_structure
together with:members:
- Macros -
.. doxygendefine:: name_of_define
- Type Definitions -
.. doxygentypedef:: name_of_type
- Enumerations -
.. doxygenenum:: name_of_enumeration
See Breathe documentation for additional information.
To provide a link to header file, use the
link custom role <link-custom-roles>
as follows:* :component_file:`path_to/header_file.h`
- Functions -
- In any case, to generate API reference, the file :idf_file:`docs/Doxyfile should be updated with paths to *.h` headers that are being documented.
- When changes are committed and documentation is build, check how this section has been rendered.
Correct annotations <../contribute/documenting-code>
in respective header files, if required.