Apache Mynewt Documentation ###########################
.. 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.
Prerequisites:
homebrew
_.. code-block:: bash
$ brew --version Homebrew 1.1.7
.. code-block:: bash
$ python --version Python 2.7.10
pip
_.. code-block:: bash
$ pip --version pip 9.0.1 from /Library/Python/2.7/site-packages (python 2.7)
Toolchain Install:
.. 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 && cd ..
$ brew install doxygen
$ sudo pip install recommonmark
Most 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
NOTE: These instructions assume that your workspace has all the mynewt repos cloned under the same parent directory.
master
and that the master
branch is checked out.Site Docs
_ to release the docs.When the master/latest documentation is deemed representative of a Mynewt version, it is time to create a versioned set.
Make sure all your mynewt-* repos are up to date and that all changes are merged and committed.
Add the new version to mynewt-documentation/docs/themes/mynewt/versions.html
mynewt-documentation/versions/*/mynewt-documentation/docs/themes/mynewt/versions.html
Make a versions/vX_Y_Z directory
Copy mynewt-documentation/* (except versions!) into versions/vX_Y_Z/mynewt-documentation
Copy the mynewt-core repo into versions/vX_Y_Z/mynewt-core
Repeat for other mynewt-* repos with doxygen docs and a /docs folder
Update the version fields in
docs/conf.py
versions/vX_Y_Z/mynewt-documentation/docs/conf.py
Add a warning that this is not the most recent documentation to:
To preview the changes:
.. code-block:: bash
cd mynewt-documentation/versions/vX_Y_Z/mynewt-documentation make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)
.. _Apache Mynewt: https://mynewt.apache.org/ .. _Sphinx: http://www.sphinx-doc.org/ .. _Doxygen: http://www.doxygen.org/ .. _Homebrew: http://brew.sh/ .. _Pip: https://pip.readthedocs.io/en/stable/installing/ .. _Breathe: http://breathe.readthedocs.io/en/latest/ .. _Site Docs: https://github.com/apache/mynewt-site#deploying-the-latest-docs