API Documentation Template¶
注解
INSTRUCTIONS
Use this file (docs/en/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.
Overview¶
注解
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
Application Example¶
注解
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/
.
API Reference¶
注解
INSTRUCTIONS
This repository provides for automatic update of API reference documentation using code markup retrieved by Doxygen from header files.
Update is done on each documentation build by invoking Sphinx extension docs/idf_extensions/run_doxygen.py for all header files listed in the
INPUT
statement of docs/doxygen/Doxyfile_common.
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 \
When the headers are expanded, any macros defined by default in
sdkconfig.h
as well as any macros defined in SOC-specificinclude/soc/*_caps.h
headers will be expanded. This allows the headers to include/exclude material based on theIDF_TARGET
value.
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-file:: inc/esp_wifi.inc
For example see docs/en/api-reference/network/esp_wifi.rst
Optionally, rather that using
*.inc
files, you may want to describe API in you own way. See docs/en/api-guides/ulp.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 as follows:
* :component_file:`path_to/header_file.h`
In any case, to generate API reference, the file docs/doxygen/Doxyfile_common 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 in respective header files, if required.