Git Product home page Git Product logo

moxygen's Introduction

Moxygen

Moxygen is a Doxygen XML to Markdown converter for C++ developers who want a minimal and beautiful solution for documentating their projects.

Moxygen is currently used in conjunction with GitBook to generate the API documentation for LibSourcey.

Features

  • Multi page output: Output single or multiple files
  • Internal linking: Anchors in comments and function definitions are supported
  • Markdown comments: Markdown in Doxygen comments are rendered
  • Doxygen groups: Doxygen grouping is supported for more organised documentation
  • Custom templates: Modify the core Markdown templates to add your own flavour
  • Optional index: Optionally render a top level index

Usage

  1. Add GENERATE_XML=YES to your Doxyfile first.
  2. Run doxygen to generate the XML documentation.
  3. Install moxygen like so: npm install moxygen -g.
  4. Run moxygen providing the folder location of the XML documentation as the first argument ie. {OUTPUT_DIRECTORY}/xml.
Usage: moxygen [options] <doxygen directory>

Options:

  -h, --help             output usage information
  -V, --version          output the version number
  -o, --output <file>    output file (must contain %s when using groups)
  -g, --groups           output doxygen groups into separate files
  -c, --classes          output doxygen classes into separate files
  -n, --noindex          disable generation of the index (no effect with `groups` option
  -a, --anchors          add anchors to internal links
  -l, --language <lang>  programming language
  -t, --templates <dir>  custom templates directory
  -q, --quiet            quiet mode

Multi-page Output

Moxygen supports the doxygen groups syntax for generating multi page documentation. Every \defgroup in your source code will be parsed and output into a separate markdown file, with internal reference updated accordingly.

Example:

moxygen --anchors --groups --output api-%s.md /path/to/doxygen/xml

Example

To get a feel for how Moxygen works you can play with the example which is located in the example folder. The example contains:

  • Documented C++ example code
  • A Doxyfile file (for doxygen 1.8.13)
  • Pre-generated XML output in example/xml
  • Pre-generated output Markdown files in example/doc

To fully build the example, follow these steps (once you've installed doxygen. See Development & Contribution, below):

  1. Rebuild the XML: run doxygen from within the example folder.
  2. Rebuild the Moxygen output: from within this directory,
node bin/moxygen.js --groups --pages --anchors --output=example/doc/api-%s.md example/xml

Development & Contribution

You can develop this project as you would any other Node project:

  1. Clone this repo.
  2. npm install from this directory.

This project is tested through integration, by building the example/. To quickly test this project:

  1. Install doxygen (brew install doxygen, choco install doxygen, for example). Only must be done once per computer.
  2. npm test from this directory. This will run Doxygen on the example/ and build the output.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.