[Open SoC Debug] Documentation Updates
philipp.wagner at tum.de
Mon Jan 23 14:42:10 CET 2017
I've had a fresh look at the documentation for OSD, as I wasn't happy
with the current, rather fragile, setup of "customized pandoc inside a
docker container". After a bit of search, I've reached the conclusion
that we're better off using reStructuredText (rst) for markup and Sphinx
for processing. This is the toolchain supported by readthedocs.org.
The benefits are:
- Clearly defined markup semantics (unlike in Markdown, where different
incompatible flavors exist and make processing hard)
- Clear extension points through directives, which enables us to choose
from many nice extensions (such as converting of block diagrams from
text into graphics), as well as writing our own ones with minimal effort
(just write some Python code).
- The documentation can be built ourselves, or hosted with almost no
configuration on readthedocs.org.
- Easy integration of API documentation, e.g. from Doxygen (through the
"breathe" doxygen -> Sphinx bridge)
As a first step in this direction, I've converted our existing
documentation into rst and pushed it to
I've also started to prepare the API documentation for libopensocdebug
and the API documentation for our hardware implementation (wait for a
really nice way to document SystemVerilog code ...). I plan to put these
parts into the software and hardware repositories, respectively, and
link everything together when building the docs. This keeps the
documentation in the same place where the sources are, making it harder
for the two to diverge.
If you agree with this general approach, I'll go on and push that to the
More information about the OpenSoCDebug