Documentation System

Read the Docs and Sphinx

Online documentation is managed via Read the Docs, which uses Sphinx as the documentation build system.

This page describes specific details for the Sming documentation build system.

reStructuredText

These have a .rst file extension. Some references you should have a read through:

Markdown .md files are supported (except for samples) but please ensure there is only one main heading (*HEADING) at the top containing the title of the Library or Component or it may be incorrectly rendered in the table of contents. If you run into problems trying to get your markdown to display correctly, then it’s probably time to move to reStructuredText!

If you need to convert existing documentation into reStructuredText take a look at pandoc. Note that their online tool doesn’t handle long files.

Source file location

Sphinx requires all document files (documents, images, etc.) to be located in one place, namely inside the docs/source directory. During the build process, documentation files from the Component, Library and Sample directories are copied:

README.md
*.rst
*.svg
*.png
*.jpg

This is also performed for any submodules declared by the COMPONENT_SUBMODULES variable in a component.mk file.

This should be sufficient for most cases. However, if additional documentation is referred to, such as in submodules belonging to a Component, then these must be listed in the component.mk file like this:

COMPONENT_DOCFILES := submodule/docs/api-guide.md submodule/api.txt

See Sming build system for more information about component.mk files.

README files

All Components, Libraries and Samples must include a README.rst or README.md file as follows:

  • Main Heading: This will be used as the title in the online documentation, so keep it brief but informative. For example, BME280 Barometric Pressure Sensor.

  • Purpose: What is the purpose of the code?

  • References: Is this based on or does it use existing code? Please include details.

  • Datasheets: If appropriate, please include links to manufacturer’s or external development websites. Note that any submodules or dependencies are automatically documented: see Sming build system for details, specifically COMPONENT_SUBMODULES and COMPONENT_DEPENDS.

You should also try to include any other information which could be useful information for a new developer. The purpose of samples projects is to demonstrate specific features or libraries, so please ensure this is adequately described.

Optionally, you may also like to include a screenshot or other diagrams or illustrations. Please use .png, .jpg or .svg files.

Attention

The README filename is case-sensitive

Attention

Please ensure there is only one top-level heading or the documentation contents will not display correctly.

You should use the available annotations to make browsing the documentation easier. Using the Sphinx roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html> will insert hyper links to the corresponding definitions. Additional roles are provided specifically for the Sming documentation - see link_roles below.

Code blocks

There are multiple ways to show syntax-higlighted literal code blocks in Sphinx. See Showing code examples for full details.

Use the code-block directive like so:

.. code-block:: c++

   for(int i = 0; i < 100; ++i) {
      goto hell;
   }

The language for highlighting is indicated. You can find a full list at pygments.org, however for consistency it is suggested that you use one of these:

text     Doesn't highlight anything
c++      C++ code examples
bash     Linux shell code
batch    Windows batch file or commands
make     Makefile
rst      reStructuredText

You can set a default like this:

.. highlight:: c++

which will apply to any subsequent use of:

.. code:block::

or, the short-hand version:

::

API Documentation

Function, structure, class and type information is extracted from comments in the source code (see Documenting the API). This is parsed using Doxygen into XML, which is then made available using the Breathe sphinx extension. You can then pull in definitions like this:

.. doxygenclass:: String
   :members:

If you wish to refer to a type within documentation, you can add a link to the definition like this:

The :cpp:class:`String` class is really useful.

This is handled using cpp inline expressions.

See Esp8266 GDBSTUB for Sming for a more complex example. At the bottom of the file we pull in the documentation for all the #defined configuration using:

.. doxygenfile:: gdbstub-cfg.h

We can then refer to a macro like this:

Don't wait on startup by setting :c:macro:`GDBSTUB_BREAK_ON_INIT` =0

In many cases including a file like this is not the best approach, perhaps using a group:

.. dogygengroup:: wstring

Or individual classes. Some experimentation may be necessary but there are plenty of examples within the main documentation to guide you.

You can use the following build variables within your Component’s component.mk file to direct doxygen parsing:

COMPONENT_DOXYGEN_INPUT

Specifies directories or files to be parsed by Doxygen. All paths are relative to the Component directory.

If you need to specify an absolute path, append directly to DOXYGEN_INPUT instead.

COMPONENT_DOXYGEN_INCLUDE

Add any directories or files which should be pre-processed but not included in the output.

If you need to specify an absolute path, append directly to DOXYGEN_INCLUDE_PATH instead.

COMPONENT_DOXYGEN_PREDEFINED

Specify any necessary pre-processor definitions. An example where this is required is for function attributes #defines which would otherwise be incorrectly interpreted as variable names and cause parsing errors:

CUSTOM_ATTR void myFunc();
^^^

So we can do this:

COMPONENT_DOXYGEN_PREDEFINED := \
   CUSTOM_ATTR=

Build (environment) variables

These are defined in the README for the corresponding Component using:

:envvar::`COM_SPEED`
Determines default serial port speed

You can refer to them like this:

Change baud rate using the :envvar:`COM_SPEED` variable.

Eclipse

You can find a good plugin editor for Eclipse by searching the marketplace for rest editor. For example, http://resteditor.sourceforge.net/. A useful feature is dealing with heading underscores, just type this:

My Heading
==

Then when you save the file it gets formatted like this:

My Heading
==========

Tables, unfortunately, do take a bit of manual formatting to get right.

Sphinx Extensions

The documentation system is easily extended to support new features. This section summarises the extensions included.

m2r2

Provides support for markdown content.

breathe

To support Doxygen integration. See API Documentation.

link-roles

A custom extension implemented in link-roles.py. See Link Roles.

sphinxcontrib.wavedrom

For implementing timing and other waveform diagrams within documents. See Servo RC PWM Control for an example.

sphinxcontrib.seqdiag

For embedding sequence diagrams, such as in the Tasks page.