[Open SoC Debug] Documentation Updates

Wei Song ws327 at cam.ac.uk
Mon Jan 23 14:49:37 CET 2017


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




More information about the OpenSoCDebug mailing list