Combine OpenOffice/Libreoffice with Doxygen results for code documentation?

3
votes

Problem

We currently want to migrate from manually to automated C-Code documentation, by re-using our previous OpenOffice results.

Background

In the last 10 years we manually generated a lot of OpenOffice (*.odt) files, including prosa like architecture, 'how it works', graphics and detailed API description. So we had a single document for each product (exported as *.pdf for our customers).

We now changed our C-Code to use Doxygen compatible formats and keywords, resulting in well formatted documentation (HTML+CHM, no PDFs until now). But this of course includes detailed API only. The aim still is to generate a single result file including prosa & graphics.

Thinking about to combine the OpenOffice & Doxygen result, we are wondering on how and in which direction to proceed:

  1. Convert *.odt => *.html and reference these in C-Code for Doxygen
  2. Convert *.odt => *.txt/png and reference these in C-Code for Doxygen
  3. Convert *.odt => *.html as a base and reference Doxygen-HTML-Results in these files
  4. Another common format available, to merge both results(?)

Question

What might be the most efficient way, to migrate from our old document style to an equivalent single documentation file - including Doxygen results?

1
cdoxygen

1 Answers

2
votes

After spending far too long trying to build complete documentation in Doxygen I have recently transitioned to Sphinx + Breathe + Doxygen. I have found that the added complexity of the multiple tools is more than offset by having usable documentation.

Doxygen is for your API documentation, keeping it inline helps encourage the API to be updated with the code.

Sphinx is for your system documentation, architecture description etc.. Sphinx is a restructured text based documentation system and you would need to convert your existing ODT documents.

Breathe is a bridge allowing you to bring your Doxygen documentation into Sphinx. The Doxygen is compiled to XML, Breathe then extracts the XML and pushes it into the compiled Sphinx documentation.

There may be other alternatives to Sphinx & Breathe but I can highly recommend a split like this. It allows Doxygen to do the API which it's strong at and allows you to do the higher level system documentation in a tool that you don't have to fight every day.