Skip to content

DocumentationGenerator.md

Latest commit

 

History

History
64 lines (50 loc) · 4.54 KB

DocumentationGenerator.md

File metadata and controls

64 lines (50 loc) · 4.54 KB
Raw

Documentation Generator Choice

Context and Problem Statement

  • we want to use an existing tool for generating usable, well-structured API documentation in HTML format from existing (inline-documented) source files
  • the "industry standard" for generating API documentation from C/C++ source code is doxygen
  • sphinx is a newer, more customizable tool for this purpose, but is mainly known for working with Python
  • the sphinx extension breathe provides directives for parsing doxygen's HTML output
  • the sphinx extension exhale can automatically parse doxygen's XML output to properly organized HTML API documentation

Considered Options

Decision Outcome

After careful evaluation, the doxygen-only approach was chosen despite initial shortcomings, because the "shortcomings" could be circumvented with rather easy workarounds.
Sphinx-based, on the other hand, ended up calling for workaround after workaround and, at its current state, was considered not worth it.
However, this could potentially change in the future, at least when new versions of breathe/exhale with better graphviz-support are released.

Consequences

  • customizability is limited from here on out
  • inserting something custom into the API-documentation (i.e. linking to the test coverage reports) could be slightly more troublesome

Pros and Cons of the Options

sphinx-based

  • (+) highly customizable (themes, output based on reStructured text, ...)
  • (+) more polished "modern" look and feel
  • (+) breathe directives can parse graphviz dot tool calls (to a certain degree)
  • (-) breathe directives parse some dot tool calls imperfectly and generate corrupted graphics or do not work at all
  • (-) output structure of exhale rather limiting for use with arbitrary projects
  • (-) exhale output potentially more hierarchical than desired
  • (-) exhale output does not include breathe directives

sphinx-based (without exhale)

  • (+) highly customizable (themes, output based on reStructured text, ...)
  • (+) more polished "modern" look and feel
  • (+) breathe directives can parse graphviz dot tool calls (to a certain degree)
  • (+) breathe apidocs command uses breathe directives
  • (-) breathe directives parse some dot tool calls imperfectly and generate corrupted graphics or do not work at all
  • (-) output of breathe apicdocs command has no proper hierarchy
  • (-) re-implementing something "exhale-like" would require a lot of work/time

doxygen-only

  • (+) full support of generating various graphics (include/caller graphs etc.) with the graphviz dot tool
  • (-) may look somewhat dated by default
  • (-) content/layout/hierarchy are not freely configurable
  • custom themes exist (see more information at the bottom) but are not "the standard" / an integrated option
  • inserting custom content is possible (by editing the HTML output afterward), but can be somewhat "hacky" and complicated

More Information