Metadata-Version: 2.1
Name: doxybook
Version: 2.1.5
Summary: Convert Doxygen XML to GitBook or Vuepress markdown files
Home-page: https://github.com/matusnovak/doxybook
Author: Matus Novak
Author-email: matusnov@gmail.com
License: MIT
Description: # 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.

        

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