[Open SoC Debug] Documentation Updates

Philipp Wagner philipp.wagner at tum.de
Tue Mar 21 16:59:35 CET 2017

Hi all,

the documentation is now live at http://opensocdebug.readthedocs.org. It 
also includes the module specs for the first time. Additionally, I've 
updated the web site to reflect these changes.

We now have a more stable base for future spec work. Next I'll work on 
getting more OpTiMSoC debug modules integrated into OSD, with associated 



On 01/23/2017 02:49 PM, Wei Song wrote:
> I like the new document. Thanks Philipp!  -Wei
> On 23/01/2017 13:42, Philipp Wagner wrote:
>> 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
>> _______________________________________________
>> OpenSoCDebug mailing list
>> OpenSoCDebug at lists.librecores.org
>> https://lists.librecores.org/listinfo/opensocdebug
> _______________________________________________
> OpenSoCDebug mailing list
> OpenSoCDebug at lists.librecores.org
> https://lists.librecores.org/listinfo/opensocdebug

More information about the OpenSoCDebug mailing list