mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-14 17:34:22 +00:00
ecc4c765cc
Fix with a workaround in unnamed unions / structs in bluetooth, i2c, sensor and uart. Current documentation parsers (sphinx under Doxygen) don't seem to understand well unnamed structs / unions. They will not generate any documentation for any documented members (see left side of http://imgur.com/mcpBXWc). A workaround is to make the parser think there is something like a struct/union/enum name that is actually something with no effect to the compiler. Naming it with __unnamed_workaround__ ensures it is clear it is a workaround while we wait for a final fix. It is #defined to be a NO-OP to the compiler and rearrange the member documentation as *@param* so we have some documentation that the non-worked around code fails to document. Anonymous structs/union that declare a variable are just given an internal name. Workarounds documented in the contribution guidelines. Change-Id: I4d32cf444f3c5e7d2fb11581e4b41f80e93c9786 Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> |
||
|---|---|---|
| .. | ||
| api | ||
| application | ||
| bluetooth | ||
| board | ||
| contribute | ||
| crypto | ||
| drivers | ||
| getting_started | ||
| kernel | ||
| porting | ||
| reference | ||
| scripts/genrest | ||
| subsystems | ||
| themes/zephyr | ||
| conf.py | ||
| doxygen.config | ||
| index.rst | ||
| Makefile | ||
| README.rst | ||
:orphan: Welcome to Zephyr Kernel ######################## .. This document is in Restructured Text Format. Find more information regarding the ReST markup in the `ReST documentation`_. This is a comment that won't show up in formatted output Welcome to the Zephyr Project. Thank you for your interest in the Zephyr Project. These instructions are designed to walk you through generating the Zephyr Project's documentation. Documentation Notes ******************* The project's documentation currently comprises the following items: * An Installation Guide for Linux host systems * A set of Collaboration Guidelines for the project. * Doxygen output from the code base for all APIs. Installing the documentation processors *************************************** Install the current version of ``Sphinx``, type: .. code-block:: bash $ git clone https://github.com/sphinx-doc/sphinx.git sphinx $ cd sphinx $ sudo -E python setup.py install $ cd .. $ git clone https://github.com/michaeljones/breathe.git breathe $ cd breathe $ sudo -E python setup.py install .. note:: Make sure that ``Doxygen`` is installed in your system. The installation of Doxygen is beyond the scope of this document. Running the Documentation Generators ************************************ Assuming that the Zephyr Project tree with the doc directory is in ``DIRECTORY``, type: .. code-block:: bash $ cd DIRECTORY/doc $ make doxy html Find the output in ``DIRECTORY/doc/_build/html/index.html`` Review the available formats with: .. code-block:: bash $ make -C DIRECTORY/doc doxy html If you want the LaTeX PDF output, you need to install all the Latex packages first. That installation is beyond the scope of this document. .. _ReST documentation: http://sphinx-doc.org/rest.html