| commit | 2a9e84f5bd38eb93a955ef4643c96fbd0d7df627 | [log] [tgz] |
|---|---|---|
| author | Wojciech Pietraszewski <wojciech.pietraszewski@codecoup.pl> | Tue Aug 13 17:48:27 2024 +0200 |
| committer | Szymon Janc <szymon.janc@codecoup.pl> | Mon Aug 19 12:09:39 2024 +0200 |
| tree | ab050e474a7c9fd37226d0a1e4eed9b0dd2299af | |
| parent | 983a6bf4f815632bee6be9d87bdded94ef71a3c9 [diff] |
docs/tutorials: Update `Air Quality Sensor` tutorial Updates the article to reflect the latest Mynewt release.
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 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`.
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 --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 recommonmark
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
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.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.htmlMake 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.pyversions/vX_Y_Z/mynewt-documentation/docs/conf.pyAdd a warning that this is not the most recent documentation to:
To preview the changes:
cd mynewt-documentation/versions/vX_Y_Z/mynewt-documentation make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)