[Open SoC Debug] Documentation Updates

Philipp Wagner philipp.wagner at tum.de
Mon Jan 23 14:42:10 CET 2017


Hi all,

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 
http://osd-test.readthedocs.io/en/latest/ and 
https://github.com/imphil/documentation.

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 
upstream repo.

Philipp


More information about the OpenSoCDebug mailing list