Again, nothing speaks against that and I fully agree! However, we should not in turn throw out the ol documentation, which is also helping people and already got a lot of work amounting to person years dumped into it.
I agree, but just to be fair, migrating to Sphinx is not dumping Doxygen, since the Sphinx documentation is still generated from Doxygen (breathe parses the output of Doxygen).
From the point of view of the developer this wouldn’t change. The thing is, autodoc of breathe only has references to Doxygen objects and doesn’t generate entries in the same way (we have digged in deeper though).
And there it where it seems antidox has an advantage, since it is able to dump an API reference output. See e. g. Generic (GNRC) network stack — RIOT 0.1.1 documentation. Sure it is not perfect (yet), but better then only generating references that then need to be refilled manually.
And there it where it seems
antidoxhas an advantage, since it is able to dump an API reference output. See e. g. Generic (GNRC) network stack — RIOT 0.1.1 documentation. Sure it is not perfect (yet), but better then only generating references that then need to be refilled manually.
I never said it didn’t 
@miri64 @jia200x @waehlisch So should we go ahead with Sphinx using breathe ?
After the discussion above: why not antidox?
bus factor ? there’s only one contributor to this project and no other project than RIOT seem to have used it.
But if antidox actually generates Documentation from our in-code documentation and breathe only creates reference files that then requires a manual redo of years of work, might it be worth to increase the usage of that tool?
Using Breathe should improve the situation with a better flexibility with documentation organization. AFAIU, the API documentation would be kept (the content) but it’s the general organization that will need special handling. Using Doxygen you get a structure automatically generated based on the group definitions and their hierarchy. I guess this will have to be handled manually with Breathe ? There’s also the possibility to autogenerate some whole parts with Breathe.
According to how I understood @jia200x and @leandrolanzieri this is not the case, so please could anyone clarify, before we have @akshaim jump down the rabbit hole?
As described above, it generates the whole hierarchy, but we still need to write the entries in several cases (e.g autodoc only generates the whole tree). This is how autodoc looks like: https://eikonomega.medium.com/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365 (check at the end).
but it’s the general organization that will need special handling
Yes, this is the case. The organization needs to be rewritten
@jia200x, @leandrolanzieri, in your original work in https://github.com/jia200x/RIOT/commits/pr/sphinx, I see that you started to rewrite the documentation (at least the examples) in reStructuredText format. But sphinx-build now also supports Markdown (see here). I guess that if we could use this feature, we could keep the original file formats.
It is also possible to convert all pure markdown files to reStructuredText with pandoc.
2 Likes
Using pandoc as a pre-procssor would also allow us to include Markdown files.
Most boards have a table detailing the properties of the MCU they use, it would be great if those could be kept in a common location and wouldn’t need to be copy & pasted between boards.
(We could even include in-line PlantUML then)