Contents
This is the project documentation for the Apache Mynewt project. It is built using Sphinx.
Each component of Mynewt contains its own specific documentation in its repo under docs. At
build time these are combined to create the full document set for publication.
The Apache Mynewt source code also contains inline comments in Doxygen format to document its APIs.
Sphinx use reStructuredText. http://www.sphinx-doc.org/en/stable/rest.html.
Embedding Doxygen generated source documentation is through the Breathe
bridge. http://breathe.readthedocs.io/en/latest/. This bridge embeds source
documentation using Sphinx's C domain. For example:
.. doxygenfile:: full/include/console/console.h
Documents can then refer to code elements using the C domain syntax:
http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
For example: :c:func:`console_read()` or :c:data:`console_input`.
Linking to other files should be relative for ease of deployment and multi-version
support. For example :doc:`../../newt/install/newt_mac`.
make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)
Note: This build toolchain is known to work on MacOS 10.11.
$ brew --version
Homebrew 1.1.7- python
$ python --version
Python 2.7.10$ pip --version
pip 9.0.1 from /Library/Python/2.7/site-packages (python 2.7)$ 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 && cd ..
$ brew install doxygen
$ sudo pip install recommonmarkMost Linux distributions provide necessary packages in their repositories.
Ubuntu/Debian .. code-block:: bash
sudo apt-get install doxygen python3-breathe python3-recommonmark
Fedora .. code-block:: bash
sudo dnf install doxygen python3-breathe python3-recommonmark