blob: 3bfbff1a28fcc43fcc49dc6463ad1472495fd9a1 [file] [log] [blame]
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.
Writing Documentation
`Sphinx`_ use reStructuredText.
Embedding `Doxygen`_ generated source documentation is through the `Breathe`_
bridge. 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:
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```.
Preview Changes
``make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)``
Setup (MacOS)
Note: This build toolchain is known to work on MacOS 10.11.
* `homebrew`_
.. code-block:: bash
$ brew --version
Homebrew 1.1.7
* python
.. 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 sphinx
$ cd sphinx && sudo -E python install && cd ..
$ git clone breathe
$ cd breathe && sudo -E python install && cd ..
$ brew install doxygen
$ sudo pip install recommonmark
Setup (Linux)
Most Linux distributions provide necessary packages in their repositories.
.. code-block:: bash
sudo apt-get install doxygen python3-breathe python3-recommonmark
.. code-block:: bash
sudo dnf install doxygen python3-breathe python3-recommonmark
.. _Apache Mynewt:
.. _Sphinx:
.. _Doxygen:
.. _Homebrew:
.. _Pip:
.. _Breathe: