Skip to content

Basic Usage

This is a command line tool that converts Doxygen generated XML files into markdown files (or JSON). You can then use the generated Markdown files to create beautiful C++ documentation using:

This project is not limited to only the static site generators listed here, you can use any other one. The config file will help you to accomplish that by specifying the behavior or file names, relative links, other requirements of the static site generator.

If you don't prefer the Markdown output generated by this tool, you can always make your own templates and supply them into this tool via the command line. If you don't want to bother with the templates, you can simply generate JSON only output, which contains partial Markdown for some things such as brief and detailed description, and use your own tool to create the documentation you want.

Command line arguments

Option Short Description
--help -h Shows this help message.
--version -v Shows the version.
--quiet -q Run in quiet mode, no stdout, display onlyerrors and warnings to stderr.
--input -i Path to the generated Doxygen XML folder.Must contain index.xml!
--output -o Path to the target folder where to generatemarkdown files.
--json -j Generate JSON only, no markdown, into theoutput path. This will also generate index.json.
--config -c Optional path to a config json file.
--config-data Optional json data to override config.
--templates -t Optional path to a folder with templates.
--generate-config Generate config file given a path to thedestination json file
--generate-templates Generate template files given a path to atarget folder.
--debug-templates -d Debug templates. This will create JSON foreach generated template.
--summary-input Path to the summary input file. This filemust contain "{{doxygen}}" string.
--summary-output Where to generate summary file. This filewill be created. Not a directory!
--example doxybook --generate-configdoxybook -i ./doxygen/xml -o

Overriding options

Note, --config-data can be used on top of --config to overwrite config properties:

Example on Windows terminal (double "" escapes the double quote):

doxybook ... --config-data "{""link_suffix"": """"}"

doxybook ... --config-data '{"link_suffix": ""}'

GitBook specific usage

GitBook requires that your SUMMARY.md file contains all of the other markdown files. If the markdown file is not listed in here, it will not be generated into a HTML file. Therefore, using --summary-input and --summary-output you can generate a SUMMARY.md file. This works by creating a "template", let's call it SUMMARY.md.tmpl. This template file will not get modified by doxybook. You will need to put in any links you see fit (external links? other markdown files?), and then you will need to add {{ doxygen }} (including the double curly backets) somewhere in this template summary. Note that the indentation of {{ doxygen }} matters and will affect the output! Example:

# Doxybook Example

* [Introduction](README.md)
  {{ doxygen }}
* [GitHub](https://github.com/matusnovak/doxybook)

And when running:

doxybook \
    --input path/to/input/xml \
    --output path/to/output/reference \
    --config path/to/config.json \
    --summary-input path/to/SUMMARY.md.tmpl \
    --summary-output path/to/SUMMARY.md

The path/to/SUMMARY.md will be generated and {{ doxygen }} will be overwritten with a nested list. It will look like this:

# Doxybook Example

* [Introduction](README.md)
  * [Classes](Classes/README.md)
    * [Engine::Exception](Classes/class_engine_1_1_exception.md)
    * [Engine::Assets::Asset](Classes/class_engine_1_1_assets_1_1_asset.md)
    [...]
  * [Namespaces](Namespaces/README.md)
    * [Engine](Namespaces/namespace_engine.md)
    [...]
* [GitHub](https://github.com/matusnovak/doxybook)

There is a sample config and summary template file located in the example/gitbook folder in this repository.

Generating JSON only

You can generate JSON only files (no Markdown) by adding --json to the command line (with no value). Such as the following:

doxybook --input path/to/input/xml --output path/to/output/reference --json