use graphviz to generate the octal addressing "graph"

[2bndy5]

I'm working on getting this repo's docs generated in Sphinx, but MD-embedded tables tend to have problems with sphinx. Most tables weem to work fine, but there is 1 table in the docs main page that is better suited as an actual graph rather than a table, namely the table in "Octal Addressing and Topology" section. Observe:

generated in doxygen

generated in sphinx (via breathe extension - so using the same source)

Notice the vertical "headers" are not shown. Also table cells don't use a vertical border (only horizontal border) due to Material Design concepts.

Solution

Enter Graphviz! I've used this tool to generate graphs in the CirPy lib when documenting the network topology. Sphinx has native integration with Graphviz, meaning the graph's source code can be directly typed into the rST file used to generate Sphinx docs. Unfortunately, Doxygen's integration with Graphviz is limited to only HTML output (which looks horrible in github's MD renderer); the XML output doesn't behave well with the breathe extension. So in our use case, for Doxygen to make use of a graph drawn with Graphviz, it must be imported like a picture ☹️ (preferably an SVG).

My recommendation is to just use a png (or svg) generated from a similar source code that I threw together for the CirPy lib's topology page. The addresses were modified to use C++ octal representation.

An interactive demonstration.

Or a more exact replica of the original table.

[2bndy5]

FYI, I went with a more exact replica graph because the preceding paragraph talked specifically about the addresses depicted in the graph (or what used to be a table).

See the graph hosted on RTD.org or in github directly. This will also show in doxygen when gh-pages get updated.

[TMRh20]

This looks really good.

On Oct 30, 2021, at 11:55 AM, Brendan @.***> wrote:

 FYI, I went with a more exact replica graph because the preceding paragraph talked specifically about the addresses depicted in the graph (or what used to be a table).

See the graph hosted on RTD.org or in github directly. This will also show in doxygen when gh-pages get updated.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.

[2bndy5]

I haven't mentioned this yet... RTD has a hidden feature that lets you auto-link between different docs hosted by RTD. This means that the user can click the datatype RF24 in the RF24Network c'tor signiture and inspect the RF24 docs effortlessly.

For the life of me, I couldn't get doxygen to do this despite what its manual says about generated tag files 😡 .