Seaborg converts Doxygen XML output to Markdown.
Seaborg is released under the terms of the The 3-Clause BSD License:
https://opensource.org/licenses/BSD-3-Clause
The Seaborg command line interface is provided as a standard NPM package:
npm install -g @seaborg/cliseaborg <input> <output>inputis the Doxygen XML output directoryoutputis the output directory
Seaborg was named in honor of the American chimist and Nobel Prize laureate
Glenn Theodore Seaborg,
co-discoverer of many chemical elements including
mendelevium. The symbol for
mendelevium is Md, which happens to match the filename extension .md used
with Markdown files. As Doxygen itself is a pun on another chemical element
(oxygen, obviously), this makes for a very happy coincidence.
Doxygen is my tool of choice when I work on C/C++/C# projects, either professionally or personally. Several of my Open Source projects hosted on GitHub use Doxygen for their reference documentation:
- PicoTest: A minimalist unit testing framework for C programs (you can find the Doxygen-generated documentation here)
- Colibri: A fast and lightweight garbage-collected datatype library
- CoATL: A companion library to Colibri that provides advanced features
While I'm perfectly happy with the raw output of Doxygen, I feel that the generated HTML files are outdated and leave too little room for customization.
And despite their limitations, newer formats such as Markdown or AsciiDocs are much more enjoyable to work with than plain HTML. Markdown itself benefits from a vast ecosystem of modern tools with native support on all major IDEs and online platforms (including GitHub). I'm personally a big fan of Docsify but there are so many static and dynamic documentation site generators to choose from!
Converting Doxygen to Markdown would ease integration with these ecosystems. Parsing the HTML is out of question, fortunately Doxygen provides raw XML output of its internal structures, and this is the path that many tools take.
I've considered using existing Doxygen-to-Markdown converters such as Doxybook, Moxygen or doxygen2md, but none of them fitted my needs: either I didn't like the output (personal opinion) or they didn't support all the features I needed, and I couldn't find the energy to study their code and contribute a patch. That is the reason why I dedided to start working on a clean state with my own views on the architecture of the solution and the desired output. Hence Seaborg!