doxybook 2.1.4

Convert Doxygen XML to GitBook or Vuepress markdown files

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

## 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**. No additional python packages necessary, only the ones included by default in python itself.

## 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 - source code + file documentation (e.g. `filename_8h.md`)
* Markdown pages through doxygen, highly do not recommend using this! (e.g. `md_src_....md`)
* Class List (e.g. `annotated.md`)
* Class Index (e.g. `classes.md`)
* Variable Index (e.g. `variables.md`)
* Function Index (e.g. `functions.md`)
* Enumeration Index (e.g. `enumerations.md`)
* Modules/groups (e.g. `modules.md`)
* Index page (if any) (e.g. `indexpage.md`)

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]

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)
--noindex NOINDEX If set to true, no search keywords will be generated
at the file headers (default: false)
--hints HINTS (Vuepress only) If set to true, hints will be
generated for the sections note, bug, and a warning
(default: true)
```

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

## 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](docs/api/index.md)
* [Related Pages](docs/api/pages.md)
* [Bug List](docs/api/bug.md)
* [My Personal Index Page](docs/api/indexpage.md)
* [Markdown test](docs/api/md_src_markdown-demo.md)
* [Test List](docs/api/test.md)
* [Todo List](docs/api/todo.md)
* [Modules](docs/api/modules.md)
* [animals](docs/api/group__animals.md)
* [Class Index](docs/api/classes.md)
* [Class List](docs/api/annotated.md)
* [namespace example](docs/api/namespaceexample.md)
* [class Animal](docs/api/classexample_1_1_animal.md)
* [struct Result](docs/api/structexample_1_1_animal_1_1_result.md)
* [class Bird](docs/api/classexample_1_1_bird.md)
* [class CustomException](docs/api/classexample_1_1_custom_exception.md)
* [class SpecialBird](docs/api/classexample_1_1_special_bird.md)
* [Files](docs/api/files.md)
* [src/](docs/api/dir_68267d1309a1af8e8297ef4c3efbcdba.md)
* [animal.h](docs/api/animal_8h.md)
* [animal.h - source](docs/api/animal_8h_source.md)
* [bird.h](docs/api/bird_8h.md)
* [bird.h - source](docs/api/bird_8h_source.md)
* [example.h](docs/api/example_8h.md)
* [example.h - source](docs/api/example_8h_source.md)
* [special_bird.h](docs/api/special__bird_8h.md)
* [special_bird.h - source](docs/api/special__bird_8h_source.md)
* [utils/](docs/api/dir_313caf1132e152dd9b58bea13a4052ca.md)
* [exception.h](docs/api/exception_8h.md)
* [exception.h - source](docs/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) 2018 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.
```
Keywords: doxygen gitbook vuepress markdown generator
Platform: UNKNOWN
Description-Content-Type: text/markdown