poxy 0.4.0

Documentation generator for C++.

poxy

Documentation generator for C++ based on Doxygen and mosra/m.css.

• Overview
• Example
• Installation
• Usage
• Config file options
• Migrating from Doxygen
• Why the name "Poxy"?
• License and Attribution

Overview

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature. Poxy builds upon both by:

• Moving the configuration out into a TOML file
• Preprocessing the Doxygen XML to fix a bunch of Doxygen bugs quirks
• Postprocessing the generated HTML to improve syntax highlighting and add a few other improvements
• Allowing source, image and example directories to be recursive or shallow on a per-directory basis
• Automatically defining C++ language feature macros based on your project's target C++ version
• Automatically integrating the cppreference.com doxygen tagfile
• Providing a number of additional built-in doxygen @alias commands
• Giving more control over the HTML inline using square-bracket [tags][/tags]
• Quite a bit more!

Example

The homepage + documentation for toml++ is built using poxy:

• homepage: marzer.github.io/tomlplusplus
• config file: poxy.toml

Installation

Prerequisites:

• Python 3
• Doxygen (preferably a version from this decade, though most will be OK)

Then:

pip install poxy

Usage

Poxy is a command-line application.

poxy [-h] [-v] [--dry] [--threads <N>] [--m.css <path>] [--doxygen <path>] [--werror] [--version] [config]

Generate fancy C++ documentation.

positional arguments:
  config            path to poxy.toml or a directory containing it (default: .)

optional arguments:
  -h, --help        show this help message and exit
  -v, --verbose     enable very noisy diagnostic output
  --dry             do a 'dry run' only, stopping after emitting the effective Doxyfile
  --threads <N>     set the number of threads to use (default: automatic)
  --m.css <path>    specify the version of m.css to use (default: uses the bundled one)
  --doxygen <path>  specify the Doxygen executable to use (default: finds Doxygen on system path)
  --werror          always treat warnings as errors regardless of config file settings
  --version         print the version and exit

The basic three-step to using Poxy is similar to Doxygen:

1. Create your poxy.toml (Poxy's answer to the Doxyfile)
2. Invoke Poxy on it: poxy path/to/poxy.toml (or simply poxy if the cwd contains the config file)
3. See your HTML documentation <cwd>/html

ℹ️ If there exists a Doxyfile or Doxyfile-mcss in the same directory as your poxy.toml it will be loaded first, then the Poxy overrides applied on top of it. Otherwise a 'default' Doxyfile is used as the base.

Config file options

For a self-contained poxy.toml example to copy and paste from, see the one used by toml++.

For a full list of options, with full descriptions, schemas and usage examples, see the Configuration options wiki page.

Migrating from Doxygen

Generally the relevant Doxyfile options will have a corresponding poxy.toml option (or be replaced by something more specific) so migration is largely a transcription and box-ticking exercise, though there are a few gotchas:

⚠️ The majority of Doxygen's options are controlled by Poxy

Very few of the configurable options from the Doxyfile remain untouched by Poxy. This is intentional; m.css is opinionated, and Poxy even moreso. There are a few instances where information can flow from a Doxyfile to Poxy, but these situations are few, and all are documented explicitly on the Configuration options wiki page.

⚠️ All relative input paths are relative to the config file, not CWD

This is in contrast to Doxygen, which has all paths be relative to the Doxygen process' current working directory regardless of where the Doxyfile was. I've always personally found that to be nothing but a source of error, so Poxy does away with it.

⚠️ Output is always emitted to CWD

Poxy always emits the output html to <cwd>/html. This is largely to simplify the HTML post-process step.

⚠️ Poxy config files are self-contained

There is no equivalent to Doxygen's @INCLUDE. If your project is structured in such a way that an N-levels-deep Doxyfile hierarchy is necessary, Poxy isn't for you.

Why the name "Poxy"?

Originally it was simply called "dox", but there's already a C++ documentation project with that name, so I smashed "python" and "dox" together and this is what I came up with.

Also "poxy" can be slang for cheap, inferior, poor quality, etc., which I thought was funny.

License and Attribution

This project is published under the terms of the MIT license.

Significant credit must go to Vladimír Vondruš (mosra) and his amazing m.css framework. Poxy bundles a fork of m.css, used per the MIT/Expat license (which can also be found in the installed python package).

Changelog

v0.4.0 - 2020-05-29

• Added config option theme
• Added version number to CSS and javascript filenames to prevent browser cache issues
• Added POXY_IMPLEMENTATION_DETAIL(...) magic macro
• Added POXY_IGNORE(...) magic macro
• Fixed alignment of nested images inside detail blocks

v0.3.4 - 2020-05-28

• Added basic using alias detection to syntax highlighter
• Added missing badges for C++23, 26 and 29

v0.3.3 - 2020-05-23

• Fixed sorting of namespace and group members
• Fixed m.css failing with new versions of doxygen due to Doxyfile.xml
• Added google structured data to \pages

v0.3.2 - 2020-05-19

• Fixed formatting of <meta> tags
• Added config option author
• Added config option robots
• Added markup tag [p]
• Added markup tag [center]

v0.3.1 - 2020-05-13

• Added config option macros
• Added command-line option --version

v0.3.0 - 2020-05-09

• Improved handling of m.css and Doxygen warnings and errors
• Added command-line option --doxygen
• Added command-line option --werror
• Added markup tag [set_parent_class]
• Added markup tag [add_parent_class]
• Added markup tag [remove_parent_class]
• Added config option images
• Added config option examples
• Added ability to specify tagfiles as URIs

v0.2.1 - 2020-05-07

• Fixed some minor autolinking issues

v0.2.0 - 2020-05-06

• Added config option source_patterns

v0.1.2 - 2020-05-02

• Fixed the Z-order of the nav bar being higher than the search overlay
• Added NDEBUG to the default set of defines

v0.1.1 - 2020-04-26

• Added an additional cleanup step to the HTML postprocessor

v0.1.0 - 2020-04-26

First public release :tada: