cankar001 / moxygen

Doxygen XML to Markdown converter

Moxygen

Moxygen is a Doxygen XML to Markdown converter for C++ developers who want a minimal and beautiful solution for documentating their projects.

Moxygen is currently used in conjunction with GitBook to generate the API documentation for LibSourcey.

Features

• Multi page output: Output single or multiple files
• Internal linking: Anchors in comments and function definitions are supported
• Markdown comments: Markdown in Doxygen comments are rendered
• Doxygen groups: Doxygen grouping is supported for more organised documentation
• Custom templates: Modify the core Markdown templates to add your own flavour
• Optional index: Optionally render a top level index

Usage

1. Add GENERATE_XML=YES to your Doxyfile first.
2. Run doxygen to generate the XML documentation.
3. Install moxygen like so: npm install moxygen -g.
4. Run moxygen providing the folder location of the XML documentation as the first argument ie. {OUTPUT_DIRECTORY}/xml.

Usage: moxygen [options] <doxygen directory>

Options:

  -h, --help             output usage information
  -V, --version          output the version number
  -o, --output <file>    output file (must contain %s when using groups)
  -g, --groups           output doxygen groups into separate files
  -c, --classes          output doxygen classes into separate files
  -n, --noindex          disable generation of the index (no effect with `groups` option
  -a, --anchors          add anchors to internal links
  -l, --language <lang>  programming language
  -t, --templates <dir>  custom templates directory
  -q, --quiet            quiet mode

Multi-page Output

Moxygen supports the doxygen groups syntax for generating multi page documentation. Every \defgroup in your source code will be parsed and output into a separate markdown file, with internal reference updated accordingly.

Example:

moxygen --anchors --groups --output api-%s.md /path/to/doxygen/xml

Example

To get a feel for how Moxygen works you can play with the example which is located in the example folder. The example contains:

• Documented C++ example code
• A Doxyfile file (for doxygen 1.8.13)
• Pre-generated XML output in example/xml
• Pre-generated output Markdown files in example/doc

To fully build the example, follow these steps (once you've installed doxygen. See Development & Contribution, below):

1. Rebuild the XML: run doxygen from within the example folder.
2. Rebuild the Moxygen output: from within this directory,

node bin/moxygen.js --groups --pages --anchors --output=example/doc/api-%s.md example/xml

Development & Contribution

You can develop this project as you would any other Node project:

1. Clone this repo.
2. npm install from this directory.

This project is tested through integration, by building the example/. To quickly test this project:

1. Install doxygen (brew install doxygen, choco install doxygen, for example). Only must be done once per computer.
2. npm test from this directory. This will run Doxygen on the example/ and build the output.