blob: df4b75f2b48c13b4fe9b9cd220e368af10fdee39 [file] [log] [blame]
Copyright (c) 2021 in-tech GmbH
This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at
SPDX-License-Identifier: EPL-2.0
.. _sphinx:
What is Sphinx
Sphinx is a python based documentation generator, using `reStructuredText <>`_ as primary import format.
Who uses Sphinx
- Everybody who publishes on `ReadTheDocs <>`_
- `OSI <>`_
Why not markdown
- Markdown was not invented to write documentation
- Right now the doxygen implementation is not pure markdown, which makes it a bit nasty to use
- Markdown does not support true references (and reference checking), figures (and captions), toc, glossary, versioning, ...
- Markdown is also supported by sphinx, but does not integrate with the cool and fancy features.
- `reStructuredText Primer <>`_
- `A "How to" Guide for Sphinx + ReadTheDocs <>`_
- `Sphinx Documentation <>`_
- `OSI Sphinx Config <>`_
Building this Documentation (Linux/Debian)
.. code-block:: bash
# install python, pip, sphinx, spellchecker, ...
sudo apt install doxygen python3 python3-pip python3-sphinx libenchant-2-2 dvipng
# install sphinx extensions
pip3 install sphinx sphinx-rtd-theme sphinx-tabs breathe exhale sphinxcontrib-spelling
# build doc (only)
mkdir build
cd build
make doc