# DoxyBook

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

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](https://github.com/matusnovak/doxybook/commit/02917de22b92aea613079b4cf81db0126e38e4d6) 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](https://github.com/matusnovak/doxybook/tree/v2.1.6).

## Live Demo

See live demo here for [Gitbook here](https://matusnovak.github.io/doxybook/gitbook/api/classexample_1_1_animal.html) or [Vuepress here](https://matusnovak.github.io/doxybook/vuepress/api/classexample_1_1_animal.html).

Alternativelly, the markdown files are located in the `doxybook/example/gitbook/api` and `doxybook/example/vuepress/api` folders.

## Requirements

You need to have **python 3.6 or newer** and [Jinja2](http://jinja.pocoo.org/docs/2.10/intro/) 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
```

## Running example

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

**Vuepress:**

```bash
# Go to the example folder
cd example

# Run doxygen and generate xml folder
doxygen Doxyfile

# Convert xml to md for Vuepress
doxybook -i temp/xml -o vuepress/api -t vuepress
# or:
# python -m doxybook doxybook -i temp/xml -o vuepress/api -t vuepress

# Run vuepress in dev mode
cd vuepress
vuepress dev

# Open http://localhost:8080
```

**Gitbook:**

```bash
# Go to the example folder
cd example

# Run doxygen and generate xml folder
doxygen Doxyfile

# Convert xml to md for GitBook
doxybook -i temp/xml -o gitbook/api -s gitbook/SUMMARY.md -t gitbook
# or:
# python -m doxybook doxybook -i temp/xml -o gitbook/api -s gitbook/SUMMARY.md -t gitbook

# Run gitbook in dev mode
cd gitbook
gitbook serve

# Open http://localhost:4000
```

## 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] [-d DEBUG]
                   [--noindex NOINDEX] [--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) or Vuepress, for
                        example: "-t vuepress" 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)
  -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

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

## Detailed usage Gitbook

1. First, create your Doxyfile. I am not going to tell you how, there are plenty of tutorials out there.
2. Set `GENERATE_XML = YES` and `XML_OUTPUT = xml` in the Doxyfile, and don't forget about `OUTPUT_DIRECTORY = temp`.
3. Run the doxygen via `doxygen Doxyfile` 
4. Create your initial GitBook.
6. 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. 
5. (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!
6. 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.
7. 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)
    * [Bug List](api/bug.md)
    * [My Personal Index Page](api/indexpage.md)
    * [Markdown test](api/md_src_markdown-demo.md)
    * [Test List](api/test.md)
    * [Todo List](api/todo.md)
  * [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)
        * [struct example::Animal::Result](api/structexample_1_1_animal_1_1_result.md)
      * [interface example::AnimalInterface](api/classexample_1_1_animal_interface.md)
      * [class example::Bird](api/classexample_1_1_bird.md)
      * [class example::CustomException](api/classexample_1_1_custom_exception.md)
      * [class example::NumericException](api/classexample_1_1_numeric_exception.md)
      * [class example::SpecialBird](api/classexample_1_1_special_bird.md)
      * [namespace example::inner_namespace](api/namespaceexample_1_1inner__namespace.md)
        * [class example::inner_namespace::Vector](api/classexample_1_1inner__namespace_1_1_vector.md)
  * [Namespace List](api/namespaces.md)
  * [Namespace Members](api/namespace_members.md)
  * [Namespace Member Functions](api/namespace_member_functions.md)
  * [Namespace Member Variables](api/namespace_member_variables.md)
  * [Namespace Member Typedefs](api/namespace_member_typedefs.md)
  * [Namespace Member Enumerations](api/namespace_member_enums.md)
  * [Class Index](api/classes.md)
  * [Class Hierarchy](api/hierarchy.md)
  * [Class Members](api/class_members.md)
  * [Class Member Functions](api/class_member_functions.md)
  * [Class Member Variables](api/class_member_variables.md)
  * [Class Member Typedefs](api/class_member_typedefs.md)
  * [Class Member Enumerations](api/class_member_enums.md)
  * [Files](api/files.md)
    * [markdown-demo.md](api/markdown-demo_8md.md)
    * [markdown-demo.md source](api/markdown-demo_8md_source.md)
    * [src](api/dir_68267d1309a1af8e8297ef4c3efbcdba.md)
      * [animal.h](api/animal_8h.md)
      * [animal.h source](api/animal_8h_source.md)
      * [animal_interface.h](api/animal__interface_8h.md)
      * [animal_interface.h source](api/animal__interface_8h_source.md)
      * [bird.h](api/bird_8h.md)
      * [bird.h source](api/bird_8h_source.md)
      * [config.h](api/config_8h.md)
      * [config.h source](api/config_8h_source.md)
      * [example.h](api/example_8h.md)
      * [example.h source](api/example_8h_source.md)
      * [special_bird.h](api/special__bird_8h.md)
      * [special_bird.h source](api/special__bird_8h_source.md)
      * [src/utils](api/dir_313caf1132e152dd9b58bea13a4052ca.md)
        * [exception.h](api/exception_8h.md)
        * [exception.h source](api/exception_8h_source.md)
* [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](https://github.com/matusnovak/doxybook/issues)

## Pull requests

[Pull requests are welcome](https://github.com/matusnovak/doxybook/pulls)

## 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.
```