Apache Mynewt Documentation

Writing Documentation
Preview Changes
Setup (macOS)
- Prerequisites
- Toolchain Install
Setup (Linux)
Deploying the latest docs
Creating a versioned set of docs

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 uses 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.

Prerequisites

Homebrew

$ 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)

Toolchain Install

$ 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

Setup (Linux)

Most Linux distributions provide necessary packages in their repositories.

Ubuntu/Debian

sudo apt-get install doxygen python3-breathe python3-recommonmark

Fedora

sudo dnf install doxygen python3-breathe python3-recommonmark

Deploying the latest docs

NOTE: These instructions assume that your workspace has all the mynewt repos cloned under the same parent directory.

Ensure that all changes are merged into master and that the master branch is checked out.
Repeat for any mynewt code repo that has documentation changes.
Follow the steps at Site Docs to release the docs.

Creating a versioned set of 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
- Also add the new version to any existing archived set.
- i.e mynewt-documentation/versions/*/mynewt-documentation/docs/themes/mynewt/versions.html
- Make sure the ‘selected’ flag is correct for the archived version
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
- and versions/vX_Y_Z/mynewt-documentation/docs/conf.py
Add a warning that this is not the most recent documentation to:
- mynewt-documentation/versions/vX_Y_Z/mynewt-documentation/docs/themes/mynewt/layout.html
- see an existing older version for example

To preview the changes:

cd mynewt-documentation/versions/vX_Y_Z/mynewt-documentation
make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)

Generating PDF File

Apply the Workaround

Due to a potential issue with Sphinx’s PDF builder, there is an additional step that needs to be performed on each dependent repository before building the documentation. The issue is related to Sphinx’s .. toctree:: directive. The output (PDF only) renders some sections in incorrect order when there is content in index.rst files used to chain source RST files together.

The workaround is to manually alter the affected files, so that there is no content but the toctree directive in those index.rst files.

First, fetch the sphinx-workaround branch for one of the repositories:

git fetch https://github.com/wpiet/mynewt-documentation sphinx-workaround
git checkout -b sphinx-workaround FETCH_HEAD

Then, rebase onto the downloaded branch:

git checkout master
git rebase sphinx-workaround

Repeat the above steps for all dependent repositories, changing the git fetch command accordingly:

git fetch https://github.com/wpiet/mynewt-core sphinx-workaround
git fetch https://github.com/wpiet/mynewt-nimble sphinx-workaround
git fetch https://github.com/wpiet/mynewt-newt sphinx-workaround
git fetch https://github.com/wpiet/mynewt-newtmgr sphinx-workaround

Build the Docs

In the mynewt-site directory run:

./build.py

In the mynewt-documentation run:

make latexpdf

This will generate the PDF file (for the version set as the latest in mkdocs.yml) in the following path: _build/latex/Mynewt.pdf