DoxyBook

New Doxybook2 has been created: https://github.com/matusnovak/doxybook2/ with better examples, template override, extended config, native executable, outputs JSON or markdown, and uses less than 10MB of RAM.

This python tool will take an xml output generated by the Doxygen and converts that into markdown to be used by GitBook, Vuepress, Docsify, or MkDocs.

Version v3.0.0 uses Jinja templates to generate Markdown files. The v3.0.0 is a massive overhaul of the XML processing and Markdown generation. See the commit 02917de to see the changes. The new v3.0.0 version has many bugfixes alongside with some additional namespace related files added into the output. If you are looking for old non templated version v2.1.6 then look into the branch doxybook/tree/v2.1.6.

Live Demo

See live demo here for Gitbook here, Vuepress here, MkDocs here, or Original here.

Requirements

You need to have python 3.6 or newer and Jinja2 package installed.

Memory usage

Needs up to 100MiB of memory. Parsing super large projects can use up to 0.5GiB of memory. For example, a project consisting of 1000 Doxygen xml files can use 550MiB of memory, but I would be worried more about VuePress or GitBook memory usage while using that many files.

Installation

Install using Python Pip: https://pypi.org/project/doxybook/

Or Install manually:

git clone https://github.com/matusnovak/doxybook.git
cd doxybook
sudo python setup.py install

To verify doxybook has installed properly, run:

doxybook -h

Compile the example

See the live demo here or alternatively you can run the examples in the following way:

# Clone this repository
git clone https://github.com/matusnovak/doxybook.git

# Go to the example folder
cd doxybook/example

# Run doxygen and generate xml folder
doxygen Doxyfile

# Convert xml to md for Vuepress
doxybook -i temp/xml -o vuepress/api -t vuepress
# Note! GitBook requires SUMMARY.md as the following:
# doxybook -i temp/xml -o gitbook/api -t gitbook -s gitbook/SUMMARY.md

# Run vuepress in dev mode
cd vuepress
vuepress dev

# Open http://localhost:8080

What files are generated?

This tool was designed to copy the file naming and structure of Doxygen html output. The naming of the files is identical except tiny changes with Class/Variable/enumeration Index pages.

All classes, namespaces, structures, and interfaces are generated, including the following additional files:

Directories (e.g. dir_....md)
Files with source code + file documentation (e.g. filename_8h.md)
Markdown pages processed through doxygen, highly do not recommend using this! (e.g. md_src_....md)
Members (e.g. class_xxx_yyy.md or namespace_xxx_yyy.md)
Class List (e.g. annotated.md)
Class Index (e.g. classes.md)
Class Members (e.g. class_members.md, class_member_enums.md, class_member_functions.md, class_member_typedefs.md, class_member_variables.md)
Class Hierarchy (.e.g hierarchy.md)
Namespace List (e.g. namespaces.md)
Namespace Members (e.g. namespace_members.md, namespace_member_enums.md, namespace_member_functions.md, namespace_member_typedefs.md, namespace_member_variables.md)
Modules/groups (e.g. modules.md)
Index page (if exists within Doxygen output as indexpage.xml) (e.g. index.md)
Any additional pages generated by Doxygen such as bugs, todo, tests

See the example folder to see all files.

Usage

> python -m doxybook -h
usage: __main__.py [-h] [-t TARGET] -i INPUT -o OUTPUT [-s SUMMARY]
                   [-l LINK_PREFIX] [-d DEBUG] [--hints HINTS]
                   [--ignoreerrors IGNOREERRORS]

Convert doxygen XML output into GitBook or Vuepress markdown output.

optional arguments:
  -h, --help            show this help message and exit
  -t TARGET, --target TARGET
                        Select the target: Gitbook (default), Docsify, MkDocs,
                        or Vuepress, for example: "-t vuepress", "-t docsify",
                        "-t mkdocs", or "-t gitbook"
  -i INPUT, --input INPUT
                        Path to doxygen generated xml folder
  -o OUTPUT, --output OUTPUT
                        Path to the destination folder
  -s SUMMARY, --summary SUMMARY
                        Path to the summary file which contains a link to
                        index.md in the folder pointed by --input (default:
                        false)
  -l LINK_PREFIX, --link-prefix LINK_PREFIX
                        Adds a prefix to all links. You can use this to
                        specify an absolute path if necessary. Docsify might
                        need this. (default: "")
  -d DEBUG, --debug DEBUG
                        Debug the class hierarchy (default: false)
  --hints HINTS         (Vuepress only) If set to true, hints will be
                        generated for the sections note, bug, and a warning
                        (default: true)
  --ignoreerrors IGNOREERRORS
                        If set to true, will continue to generate Markdown
                        files even if an error has been detected (default:
                        false)

Detailed usage Vuepress

First, create your Doxyfile. I am not going to tell you how, there are plenty of tutorials out there.
Set GENERATE_XML = YES and XML_OUTPUT = xml in the Doxyfile, and don't forget about OUTPUT_DIRECTORY = temp (or any other directory).
Run the doxygen via doxygen Doxyfile
Create your initial Vuepress configuration (optional).
Run doxybook as: doxybook -i temp/xml -o docs/api -t vuepress (paths are relative).
Then run vuepress dev and go to http://localhost:8080.

Detailed usage Docsify or MkDocs

Same as VuePress, except use -t docsify or -t mkdocs when running doxybook.

Detailed usage Gitbook

First, create your Doxyfile. I am not going to tell you how, there are plenty of tutorials out there.
Set GENERATE_XML = YES and XML_OUTPUT = xml in the Doxyfile, and don't forget about OUTPUT_DIRECTORY = temp.
Run the doxygen via doxygen Doxyfile
Create your initial GitBook.
Create an empty folder where the markdown files should be generated. For the purpose of this example, we will put it in the docs/api folder.
(optional) In your SUMMARY.md create a link to the docs/api/index.md with any text, for example: * [Lorem Ipsum](docs/api/index.md). This file can be any kind of markdown file. However, the file index.md needs to be inside the folder where the markdown files are going to be generated. Doxybook will find this link and will generated a sub-list below that markdown link. Anything you have written after the * [Lorem Ipsum](docs/api/index.md) will not be affected, only the sub-list items. Note that if you put any list item or sub-lists of * [Lorem Ipsum](docs/api/index.md) they will be REMOVED!
Run doxybook as: doxybook -i temp/xml -o docs/api -s SUMMARY.md -t gitbook (paths are relative) The -s SUMMARY.md is optional, if you provide a vaid path to the SUMMARY.md file then the doxybook will alter the contents with links to generated markdown files.
Then build your GitBook as: gitbook build, or serve it as gitbook serve and go to http://localhost:4000, or upload the contents of _book folder into gh-pages on GitHub.

Having errors while generating markdown files?

Run doxybook as doxybook --ignoreerrors true -i ... -o ... -t .... The files will be generated, but some things may be missing.

How does the SUMMARY.md work here? (Gitbook only)

GitBook has a big fault that anything not listed in SUMMARY.md will get ignored. Therefore the doxybook needs to alter the SUMMARY.md. Yes, this is optional, in case GitBook will be fixed in the future.

For example, given this summary file:

# Summary

* [Introduction](README.md)
* [Documentation](docs/api/index.md)
  * [This will get deleted](whatever.md)
* [Something else](something-else.md)
* [Go to my website](http://mywebsite.com/)

After running doxybook, the summary will become this code below. Notice how * [This will get deleted](whatever.md) has vanished. The doxybook will only modify anything that is a child item of * [Documentation](docs/api/index.md) regardless of the indentation. Also, you do not need to remove any generated links to docs/api (or whatever folder you have used) as it will be sraped in any re-run of the doxybook and generated from scratch.

# Summary

* [Introduction](README.md)
* [Documentation](api/index.md)
  * [Related Pages](api/pages.md)
    ... etc
  * [Modules](api/modules.md)
    * [Some organism example](api/group__organism.md)
      * [An animal group example](api/group__animals.md)
  * [Class List](api/annotated.md)
    * [namespace example](api/namespaceexample.md)
      * [class example::Animal](api/classexample_1_1_animal.md)
        ... etc
  * [Namespace List](api/namespaces.md)
  ... etc
* [Something else](something-else.md)
* [Go to my website](http://mywebsite.com/)

Found a bug or want to request a feature?

Feel free to do it on GitHub issues

Pull requests

Pull requests are welcome

Contact

Use GitHub issues or contact me through my email (see my GitHub profile page).

License

MIT License

Copyright (c) 2019 Matus Novak

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

matusnovak / doxybook