Documentation generator for C++ based on Doxygen and mosra/m.css.
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:
@alias commands[tags][/tags]currentColorThe homepage + documentation for toml++ is built using poxy:
poxy.tomlpip install poxy
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:
poxy.toml (Poxy's answer to the Doxyfile)poxy path/to/poxy.toml (or simply poxy if the cwd contains the config file)<cwd>/htmlFor 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.
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:
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.
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.
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.
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.
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.
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).
POXY_IMPLEMENTATION_DETAIL_IMPL appearing in HTML in some circumstancesModuleNotFoundError error in Python 3.12 (#38) (@dekinet)--bug-report keep a copy of the original (pre-pre-processed?) XMLexcluded_symbols (a.k.a. Doxygen's EXCLUDE_SYMBOLS) (#36) (@Guekka)'tuple' object has no attribute 'week' error on Python <= 3.8--min-version and --squash-patches for more control over --git-tags mode--git-tagsmain_page (a.k.a. USE_MDFILE_AS_MAINPAGE)CHANGELOG too far up the directory heirarchy (now stops when a .git folder is encountered)* wildcards in implementation_headers--bug-report regression (#29) (@wroyca)template<> noise in details views@ref links to #id anchors on the same page being treated as external linkspyproject.tomlauto in trailing return types (#26) (@wroyca)sponsortwittertemplate<> lines in summary viewstemplate<> lines in page headers (they now wrap)argparse feature on Python <= 3.8 (#20) (@fwerner)tomligithub and gitlab config options not accepting periods (.)AttributeError during XML post-processing (#17) (@wroyca)--bug-report<a> tags in navbarstatic keyword sometimes appearing twice on variablesconstexpr keyword sometimes leaking into variable typeconstinittomllib or tomli if pytomlpp is not available--html, --no-html--xml, --no-xml--no-werrorCHANGES to the set of candidate changelog filenames--xmlonly--doxygenValueError when reading some SVG filesnavbar option allowing duplicatesconcepts to the default set of links in navbarnavbar values all and default--drygitlab (#13) (@wroyca)doxygen.exe location discovery on WindowsCHANGELOG location discoveryhtml/poxy<link>, <meta> and <script> tags not being included in <head> when a file was excluded from post-processingtheme command-line optionhtml_header config option optiongithub is setchangelog config optionNUM_PROC_THREADS--dryfriend keyword sometimes leaking into function return types--nocleanup to --help outputconsteval keywordfriend as part of a function's return type#anchor links--ppinclude and --ppexcludeimplementation_headers not working when paths use backslashesimplementation_headers doesn't match anything--xmlonly[code_blocks] functionality.dirs being glommed as source pathsscriptsstylesheetsjquerycustom themeHOME.md as main page<code> blocks.poxy-toc to table-of-contents elementslight and dark themesthemePOXY_IMPLEMENTATION_DETAIL(...) magic macroPOXY_IGNORE(...) magic macrousing alias detection to syntax highlighterDoxyfile.xml\pages<meta> tagsauthorrobots[p][center]macros--version--doxygen--werror[set_parent_class][add_parent_class][remove_parent_class]imagesexamplessource_patternsNDEBUG to the default set of definesFirst public release :tada:
FAQs
Documentation generator for C++.
We found that poxy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.