135 lines
5.1 KiB
ReStructuredText
135 lines
5.1 KiB
ReStructuredText
.. _zephyr_doc:
|
|
|
|
Zephyr documentation
|
|
####################
|
|
|
|
These instructions will walk you through generating the Zephyr Project's
|
|
documentation on your local system using the same documentation sources
|
|
as we use to create the online documentation found at
|
|
https://zephyrproject.org/doc
|
|
|
|
Documentation overview
|
|
**********************
|
|
|
|
Zephyr Project content is written using the reStructuredText markup
|
|
language (.rst file extension) with Sphinx extensions, and processed
|
|
using sphinx to create a formatted stand-alone website. Developers can
|
|
view this content either in its raw form as .rst markup files, or you
|
|
can generate the HTML content and view it with a web browser directly on
|
|
your workstation. This same .rst content is also fed into the Zephyr
|
|
Project's public website documentation area (with a different theme
|
|
applied).
|
|
|
|
You can read details about `reStructuredText`_, and `Sphinx`_ from
|
|
their respective websites.
|
|
|
|
The project's documentation contains the following items:
|
|
|
|
* ReStructuredText source files used to generate documentation found at the
|
|
https://zephyrproject.org/doc website. Most of the reStructuredText sources
|
|
are found in the ``/doc`` directory, but others are stored within the
|
|
code source tree near their specific component (such as ``/samples`` and
|
|
``/boards``)
|
|
|
|
* Doxygen-generated material used to create all API-specific documents
|
|
also found at https://zephyrproject.org/doc
|
|
|
|
* Script-generated material for kernel configuration options based on Kconfig
|
|
files found in the source code tree
|
|
|
|
The reStructuredText files are processed by the Sphinx documentation system,
|
|
and make use of the breathe extension for including the doxygen-generated API
|
|
material. Additional tools are required to generate the
|
|
documentation locally, as described in the following sections.
|
|
|
|
Installing the documentation processors
|
|
***************************************
|
|
|
|
Our documentation processing has been tested to run with:
|
|
|
|
* Doxygen version 1.8.11
|
|
* Sphinx version 1.5.5
|
|
* Breathe version 4.6.0
|
|
* docutils version 0.13.1
|
|
|
|
Begin by cloning a copy of the git repository for the zephyr project and
|
|
setting up your development environment as described in :ref:`getting_started`
|
|
or specifically for Ubuntu in :ref:`installation_linux`. (Be sure to
|
|
export the environment variables ``ZEPHYR_GCC_VARIANT`` and
|
|
``ZEPHYR_SDK_INSTALL_DIR`` as documented there.)
|
|
|
|
Other than ``doxygen``, the documentation tools should be installed using ``pip``.
|
|
If you don't already have pip installed, these commands will install it:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ curl -O 'https://bootstrap.pypa.io/get-pip.py'
|
|
$ ./get-pip.py
|
|
$ rm get-pip.py
|
|
|
|
The documentation generation tools are included in the set of tools
|
|
expected for the Zephyr build environment and so are included in
|
|
``requirements.txt``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ sudo -E apt-get install doxygen
|
|
$ pip install -r scripts/requirements.txt
|
|
|
|
Documentation presentation theme
|
|
********************************
|
|
|
|
Sphinx supports easy customization of the generated documentation
|
|
appearance through the use of themes. Replace the theme files and do
|
|
another ``make htmldocs`` and the output layout and style is changed.
|
|
The ``read-the-docs`` theme is installed as part of the
|
|
``requirements.txt`` list above, and will be used if it's available, for
|
|
local doc generation.
|
|
|
|
|
|
Running the documentation processors
|
|
************************************
|
|
|
|
The ``/doc`` directory in your cloned copy of the Zephyr project git
|
|
repo has all the .rst source files, extra tools, and Makefile for
|
|
generating a local copy of the Zephyr project's technical documentation.
|
|
Assuming the local Zephyr project copy is ``~/zephyr``, here are the
|
|
commands to generate the html content locally:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cd ~/zephyr
|
|
$ source zephyr-env.sh
|
|
$ cd doc
|
|
$ make htmldocs
|
|
|
|
Depending on your development system, it will take about 15 minutes to
|
|
collect and generate the HTML content. When done, the HTML output will
|
|
be in ``~/zephyr/doc/_build/html/index.html``
|
|
|
|
Filtering expected warnings
|
|
***************************
|
|
|
|
Alas, there are some known issues with the doxygen/Sphinx/Breathe
|
|
processing that generates warnings for some constructs, in particular
|
|
around unnamed structures in nested unions or structs. Also, adding
|
|
qualifiers to a function declaration, like __deprecated, can generate a
|
|
warning. While these issues are being considered for fixing in
|
|
Sphinx/Breathe, we've added a post-processing filter on the output of
|
|
the documentation build process to remove "expected" messages from the
|
|
generation process output.
|
|
|
|
The output from the Sphinx build is processed by the python script
|
|
``scripts/filter-known-issues.py`` together with a set of filter
|
|
configuration files in the ``.known-issues/doc`` folder. (This
|
|
filtering is done as part of the ``doc/Makefile``.)
|
|
|
|
If you're contributing components included in the Zephyr API
|
|
documentation and run across these warnings, you can include filtering
|
|
them out as "expected" warnings by adding a conf file to the
|
|
``.known-issues/doc`` folder, following the example of other conf files
|
|
found there.
|
|
|
|
.. _reStructuredText: http://sphinx-doc.org/rest.html
|
|
.. _Sphinx: http://sphinx-doc.org/
|