poxy 0.17.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]
• Adding a switchable light theme
• Adding support for C++20 concepts
• Self-hosting fonts to reduce external HTTP requests
• Inlining SVGs so they can take advantage of currentColor
• 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.7+
• Doxygen 1.8.20+ (must be visible on system path)

Then:

pip install poxy

Usage

Poxy is a command-line application.

usage: poxy [-h] [-v] [--html | --no-html] [--ppinclude <regex>] [--ppexclude <regex>]
            [--theme {light,dark,custom}] [--threads N] [--version] [--xml | --no-xml]
            [--werror | --no-werror] [--bug-report] [--git-tags]
            [--squash-patches | --no-squash-patches] [--min-version <version>]
            [config]

  _ __   _____  ___   _
 | '_ \ / _ \ \/ / | | |
 | |_) | (_) >  <| |_| |
 | .__/ \___/_/\_\\__, |
 | |               __/ |
 |_|              |___/  v0.17.0 - github.com/marzer/poxy

Generate fancy C++ documentation.

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

options:
  -h, --help            show this help message and exit
  -v, --verbose         enable very noisy diagnostic output
  --html, --no-html     specify whether HTML output is required
  --ppinclude <regex>   pattern matching HTML file names to post-process (default: all)
  --ppexclude <regex>   pattern matching HTML file names to exclude from post-processing (default: None)
  --theme {light,dark,custom}
                        sets the default visual theme (default: read from config)
  --threads N           set the number of threads to use (default: automatic)
  --version             print the version and exit
  --xml, --no-xml       specify whether XML output is required
  --werror, --no-werror
                        treat warnings as errors (default: read from config)
  --bug-report          captures all output in a zip file for easier bug reporting.
  --git-tags            add git-tag-based semver version switcher to the generated HTML
  --squash-patches, --no-squash-patches
                        when using --git-tags and two version tags differ by a patch number,
                        generate docs for the highest one only (default: True)
  --min-version <version>
                        sets the minimum version number to emit when using --git-tags,
                        or a negative integer to mean "the last N versions". (default: None)

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

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

Many of Doxygen's various knobs and switches are manually overridden by Poxy, and are not configurable. This is intentional! Doxygen tends to break in hilarious and fantastic ways from one release to the next; reducing it to a very 'locked-down' back-end minimizes the damage future regressions can do, allowing me to keep most debugging python-side.

If there is some Doxygen feature you would like exposed in Poxy, please create a feature request.

⚠️ 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 HTML to <cwd>/html and XML to <cwd>/xml. You cannot use your config file to specify where any output will be placed - use your command-line environment for this purpose instead by changing the CWD. This is to eliminate nasty surprises brought on by goofy config file decisions and help with portability.

⚠️ Poxy config files are self-contained

There is no equivalent to Doxygen's @INCLUDE. If your project is structured in such a way that a multi-level 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 Doxygen theme. 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.17.0 - 2024-04-21

• added arguments --min-version and --squash-patches for more control over --git-tags mode

v0.16.0 - 2024-01-28

• added multi-version mode argument --git-tags
• added colour to output

v0.15.0 - 2023-12-08

• added config option main_page (a.k.a. USE_MDFILE_AS_MAINPAGE)
• fixed searching for CHANGELOG too far up the directory heirarchy (now stops when a .git folder is encountered)

v0.14.0 - 2023-11-25

• added the use of * wildcards in implementation_headers

v0.13.9 - 2023-09-10

• fixed crash on Doxygen <= 1.8.17 (#33) (@tim-janik)

v0.13.8 - 2023-09-09

• fixed regression for Python <= 3.8 (#32) (@tim-janik)

v0.13.7 - 2023-08-17

• fixed minor syntax highlighting issues

v0.13.6 - 2023-08-10

• update m.css to fix libgs.so lookup (#31) (@wroyca, @mosra)

v0.13.5 - 2023-08-09

• fixed --bug-report regression (#29) (@wroyca)

v0.13.4 - 2023-08-06

• fixed excessive template<> noise in details views

v0.13.3 - 2023-08-01

• fixed floating TOCs sometimes clipping off the bottom of the screen when the viewport was vertically narrow

v0.13.2 - 2023-07-31

• fixed doxygen's @ref links to #id anchors on the same page being treated as external links
• added auto-linking for C++ named requirements
• minor style fixes

v0.13.1 - 2023-07-29

• fixed crash regression with Doxygen 1.9.7
• fixed issues with [tag] substitution
• minor style fixes

v0.13.0 - 2023-07-28

• migrated to pyproject.toml
• fixed footer being off-center (#24) (@wroyca)
• fixed redundant auto in trailing return types (#26) (@wroyca)
• added config option sponsor
• added config option twitter

v0.12.7 - 2023-07-27

• allowed the use of square-bracket [tags] in more places

v0.12.6 - 2023-07-25

• fixed overlong template<> lines in summary views
• fixed function parameter names greedily wrapping in details tables

v0.12.5 - 2023-07-20

• fixed overlong template<> lines in page headers (they now wrap)

v0.12.4 - 2023-03-23

• fixed changelog not auto-linking with some versions of Doxygen

v0.12.3 - 2023-02-09

• fixed backwards-incompatible use of a newer argparse feature on Python <= 3.8 (#20) (@fwerner)

v0.12.2 - 2023-02-08

• switched default TOML lib to tomli

v0.12.1 - 2022-11-22

• fixed github and gitlab config options not accepting periods (.)

v0.12.0 - 2022-11-13

• fixed AttributeError during XML post-processing (#17) (@wroyca)
• added command-line option --bug-report
• improved diagnostic text in some areas

v0.11.1 - 2022-10-23

• fixed crash when using <a> tags in navbar

v0.11.0 - 2022-10-21

• added syntax highlighting for functions
• improved syntax highlighting of typenames

v0.10.2 - 2022-10-16

• fixed crash when tagfile is disabled
• fixed a few syntax highlighting edge-cases
• fixed non-determinism in XML output formatting
• improved performance of syntax highlighting post-process
• minor style fixes

v0.10.1 - 2022-10-15

• minor style fixes

v0.10.0 - 2022-10-14

• fixed static keyword sometimes appearing twice on variables
• fixed constexpr keyword sometimes leaking into variable type
• fixed newer versions of pygments adding unnecessary markup to whitespace
• fixed malformed trailing return types in some circumstances
• fixed changelog page sometimes not having a table-of-contents
• added support for C++20's constinit
• added fallback to tomllib or tomli if pytomlpp is not available
• added command-line options --html, --no-html
• added command-line options --xml, --no-xml
• added command-line option --no-werror
• added CHANGES to the set of candidate changelog filenames
• deprecated command-line option --xmlonly
• removed command-line option --doxygen

v0.9.1 - 2022-10-04

• fixed SVG inlining not preserving original image class attributes
• fixed ValueError when reading some SVG files
• fixed navbar option allowing duplicates
• fixed custom navbar items always being transformed to lowercase
• fixed navbar generating links to empty pages
• added concepts to the default set of links in navbar
• added navbar values all and default
• reduced I/O churn during HTML post-processing
• removed command-line option --dry

v0.9.0 - 2022-10-03

• added support for C++20 concepts

v0.8.2 - 2022-10-01

• added post-process to inline all local SVGs
• minor style fixes

v0.8.1 - 2022-09-30

• minor style fixes

v0.8.0 - 2022-09-29

• added config option gitlab (#13) (@wroyca)
• added ixx module extension in source patterns (#11) (@wroyca)
• added support for multi-codepoint emojis
• improved doxygen.exe location discovery on Windows
• improved CHANGELOG location discovery
• moved all poxy assets in the generated HTML to html/poxy
• self-hosted google fonts in generated HTML (instead of requiring additional HTTP requests on page load) (#6)
• removed ability to override m.css implementation
• removed legacy support for reading config options from neighbouring Doxyfiles
• overhauled the light theme
• many minor style fixes and tweaks

v0.7.1 - 2022-08-17

• fixed crash on python <= 3.8 (#9) (@wroyca)

v0.7.0 - 2022-08-16

• fixed some <link>, <meta> and <script> tags not being included in <head> when a file was excluded from post-processing
• added theme command-line option
• added html_header config option option
• added automatic generation of github links in changelog when config option github is set
• added new light theme
• added dynamic switch for dark/light theme
• removed text from github icon on navbar (#5) (@wroyca)
• removed excessive spacing between article sections (#5) (@wroyca)
• many minor style fixes and tweaks

v0.6.1 - 2022-08-16

• fixed multi-row navbar occluding page content (#3) (@wroyca)

v0.6.0 - 2022-08-14

• fixed malformed error messages in some circumstances
• added builtin C++ standard macros for C++23
• added changelog config option
• updated cppreference.com tagfile

v0.5.7 - 2022-05-17

• fixed being able to pass >= 33 threads to Doxygen's NUM_PROC_THREADS

v0.5.6 - 2022-05-14

• fixed path error when using --dry
• fixed friend keyword sometimes leaking into function return types
• added additional language code block aliases
• added --nocleanup to --help output
• added support for C++20's consteval keyword

v0.5.5 - 2022-04-16

• fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)

v0.5.4 - 2022-04-15

• updated m.css
• updated emoji database

v0.5.3 - 2021-12-12

• fixed Doxygen bug that would sometimes treat keywords like friend as part of a function's return type
• Blacklisted schema 0.7.5 because it's broken

v0.5.2 - 2021-11-02

• fixed over-eager link-replacement for internal #anchor links
• added command-line options --ppinclude and --ppexclude

v0.5.1 - 2021-10-09

• fixed over-eager link replacement causing text to be deleted

v0.5.0 - 2021-09-11

• fixed a crash during HTML post-processing
• fixed implementation_headers not working when paths use backslashes
• added warnings when implementation_headers doesn't match anything

v0.4.5 - 2021-06-08

• added command-line option --xmlonly

v0.4.3 - 2021-05-31

• fixed regression in [code_blocks] functionality
• fixed minor issues in syntax highlighter
• added symbols from doxygen tagfiles to the syntax highlighter
• minor style tweaks

v0.4.1 - 2021-05-30

• fixed .dirs being glommed as source paths
• added config option scripts
• added config option stylesheets
• added config option jquery
• added custom theme
• added ability to use HOME.md as main page
• added additional fix for inline <code> blocks
• added .poxy-toc to table-of-contents elements
• added floating page table-of-contents
• removed m.css favicon fallback
• made improvements to the light and dark themes
• updated C++ doxygen tagfile

v0.4.0 - 2021-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 - 2021-05-28

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

v0.3.3 - 2021-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 - 2021-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 - 2021-05-13

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

v0.3.0 - 2021-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 - 2021-05-07

• fixed some minor autolinking issues

v0.2.0 - 2021-05-06

• added config option source_patterns

v0.1.2 - 2021-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 - 2021-04-26

• added an additional cleanup step to the HTML postprocessor

v0.1.0 - 2021-04-26

First public release :tada: