Writing Documentation for Component

This document covers our documentation process for component.

In short, to generate HTML files, run:

make

When header files are updated, be sure to run clean target.

make clean all

• Requirements
• Files and Directories
• Makefile targets
  • all Target
  • html Target
  • build-doxygen Target
  • clean Target
• Writing documentation
• Deploying the documentation

Requirements

Install the following software.

• GNU make
• doxygen
• sphinx
• sphinx_rtd_theme
• breathe
• ruby (for bin/eil-q)

sphinx is used because the default HTML files generated by doxygen looks not so human-friendly.

breathe and sphinx_rtd_theme are extensions of sphinx.

Files and Directories

• index.rst The top page of the documentation
• conf.py Configuration file for sphinx (and breathe)
• doxygen.conf Configuration file for doxygen
• Makefile GNU Makefile to automate HTML generation
• doxygen.log Log file of doxygen (can be safely removed)
• _docs/xml Output directory for doxygen (can be safely removed)
• _build/html Output directory for sphinx (can be safely removed)

Makefile targets

Makefile has a few targets to build the documentation. The most notable ones are:

• make all or make
• make clean

all Target

This is the default target, which invokes html target.

make all

# or

make

html Target

This target generates HTML files after invoking build-doxygen.

make html

The generated HTML files is under _build/html directory. To see the HTML files, run:

firefox _build/html/index.html

By default, warnings are treated as errors. To ignore errors, probably because the code is old and fixing it takes a long time, use SPHINX_FLAGS, which overrides the default value.

make SPHINX_FLAGS=""

There are other variables that can be overridden in Makefile, such as variables assigned with ?=.

FOO?=   bar

build-doxygen Target

This target parses the source code (header files only).

make build-doxygen

clean Target

This targets clean up unnecessary files and directories. Be sure to run this target when header files are modified.

make clean

Update the HTML files.

make clean all

Writing documentation

The overview of the documentation process is:

1. Write API documentation in the code
2. Write index.rst and reference the API documentation from it by doxygenfile directive
3. Generate HTML files by make
4. Verify the result and fix issues until the output is satisfactory
5. Clean uo by make clean (optional).

When writing a component, describe functions, macros, structures, among other things, in the code. Read how to document APIs at: Writing API Description. The API documentation in the code is parsed by doxygen. The output of doxygen can be later used in documentation files under this directory, such as index.rst.

In addition to the API documentation, index.rst is where additional information, such as usages, notes, and warnings are documented.

Read Basic Syntax at ESP-Docs User Guide for general formatting rules.

To include the automatically generated API documentation, doxygenfile (the documentation) is the directive to generate the appropriate output for the contents of a source file. If the component has just a single header file, filename.h for instance, this is what you need in index.rst.

Welcome to Foo's documentation!
===============================

.. doxygenfile:: filename.h

Deploying the documentation

By default, the documentation is published on GitHub Pages when the component has been released. See publish-gh-pages.yml and build-docs.yml at esp-idf-lib/shared-workflows.