Package: poxy
poxyDocumentation generator for C++ based on Doxygen andmosra/m.css.OverviewExampleInstallationUsageConfig file optionsMigrating from DoxygenWhy the name "Poxy"?License and AttributionOverviewmosra/m.cssis 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.Poxybuilds upon both by:Moving the configuration out into a TOML filePreprocessing the Doxygen XML to fix a bunch of DoxygenbugsquirksPostprocessing the generated HTML to improve syntax highlighting and add a few other improvementsAllowing source, image and example directories to be recursive or shallow on a per-directory basisAutomatically defining C++ language feature macros based on your project's target C++ versionAutomatically integrating the cppreference.com doxygen tagfileProviding a number of additional built-in doxygen@aliascommandsGiving more control over the HTML inline using square-bracket[tags][/tags]Adding a switchable light themeAdding support for C++20 conceptsSelf-hosting fonts to reduce external HTTP requestsInlining SVGs so they can take advantage ofcurrentColorQuite a bit more!ExampleThe homepage + documentation fortoml++is built using poxy:homepage:marzer.github.io/tomlplusplusconfig file:poxy.tomlInstallationPrerequisites:Python 3.7+Doxygen 1.8.20+ (must be visible on system path)Then:pip install poxyUsagePoxy 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] [config]

  _ __   _____  ___   _
 | '_ \ / _ \ \/ / | | |
 | |_) | (_) >  <| |_| |
 | .__/ \___/_/\_\\__, |
 | |               __/ |
 |_|              |___/  v0.16.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 HTMLThe basic three-step to using Poxy is similar to Doxygen:Create yourpoxy.toml(Poxy's answer to theDoxyfile)Invoke Poxy on it:poxy path/to/poxy.toml(or simplypoxyif the cwd contains the config file)See your HTML documentation<cwd>/htmlConfig file optionsFor a self-containedpoxy.tomlexample to copy and paste from,
seethe one used by toml++.For a full list of options, with full descriptions, schemas and usage examples, see theConfiguration optionswiki page.Migrating from DoxygenGenerally the relevantDoxyfileoptions will have a correspondingpoxy.tomloption
(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 PoxyMany 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 afeature request.⚠️ All relative input paths are relative to the config file,notCWDThis 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 CWDPoxy always emits HTML to<cwd>/htmland 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-containedThere 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 AttributionThis project is published under the terms of theMIT license.Significant credit must go to Vladimír Vondruš (mosra) and his amazingm.cssDoxygen theme.
Poxy bundles a fork of m.css, used per theMIT/Expat license(which can also be found in the installed python package).Changelogv0.16.0 - 2024-01-28added multi-version mode argument--git-tagsadded colour to outputv0.15.0 - 2023-12-08added config optionmain_page(a.k.a.USE_MDFILE_AS_MAINPAGE)fixed searching forCHANGELOGtoo far up the directory heirarchy (now stops when a.gitfolder is encountered)v0.14.0 - 2023-11-25added the use of*wildcards inimplementation_headersv0.13.9 - 2023-09-10fixed crash on Doxygen <= 1.8.17 (#33) (@tim-janik)v0.13.8 - 2023-09-09fixed regression for Python <= 3.8 (#32) (@tim-janik)v0.13.7 - 2023-08-17fixed minor syntax highlighting issuesv0.13.6 - 2023-08-10update m.css to fix libgs.so lookup (#31) (@wroyca, @mosra)v0.13.5 - 2023-08-09fixed--bug-reportregression (#29) (@wroyca)v0.13.4 - 2023-08-06fixed excessivetemplate<>noise in details viewsv0.13.3 - 2023-08-01fixed floating TOCs sometimes clipping off the bottom of the screen when the viewport was vertically narrowv0.13.2 - 2023-07-31fixed doxygen's@reflinks to#idanchors on the same page being treated as external linksadded auto-linking for C++named requirementsminor style fixesv0.13.1 - 2023-07-29fixed crash regression with Doxygen 1.9.7fixed issues with [tag] substitutionminor style fixesv0.13.0 - 2023-07-28migrated topyproject.tomlfixed footer being off-center (#24) (@wroyca)fixed redundantautoin trailing return types (#26) (@wroyca)added config optionsponsoradded config optiontwitterv0.12.7 - 2023-07-27allowed the use of square-bracket [tags] in more placesv0.12.6 - 2023-07-25fixed overlongtemplate<>lines in summary viewsfixed function parameter names greedily wrapping in details tablesv0.12.5 - 2023-07-20fixed overlongtemplate<>lines in page headers (they now wrap)v0.12.4 - 2023-03-23fixed changelog not auto-linking with some versions of Doxygenv0.12.3 - 2023-02-09fixed backwards-incompatible use of a newerargparsefeature on Python <= 3.8 (#20) (@fwerner)v0.12.2 - 2023-02-08switched default TOML lib totomliv0.12.1 - 2022-11-22fixedgithubandgitlabconfig options not accepting periods (.)v0.12.0 - 2022-11-13fixedAttributeErrorduring XML post-processing (#17) (@wroyca)added command-line option--bug-reportimproved diagnostic text in some areasv0.11.1 - 2022-10-23fixed crash when using<a>tags in navbarv0.11.0 - 2022-10-21added syntax highlighting for functionsimproved syntax highlighting of typenamesv0.10.2 - 2022-10-16fixed crash when tagfile is disabledfixed a few syntax highlighting edge-casesfixed non-determinism in XML output formattingimproved performance of syntax highlighting post-processminor style fixesv0.10.1 - 2022-10-15minor style fixesv0.10.0 - 2022-10-14fixedstatickeyword sometimes appearing twice on variablesfixedconstexprkeyword sometimes leaking into variable typefixed newer versions of pygments adding unnecessary markup to whitespacefixed malformed trailing return types in some circumstancesfixed changelog page sometimes not having a table-of-contentsadded support for C++20'sconstinitadded fallback totomllibortomliifpytomlppis not availableadded command-line options--html,--no-htmladded command-line options--xml,--no-xmladded command-line option--no-werroraddedCHANGESto the set of candidate changelog filenamesdeprecated command-line option--xmlonlyremoved command-line option--doxygenv0.9.1 - 2022-10-04fixed SVG inlining not preserving original image class attributesfixedValueErrorwhen reading some SVG filesfixednavbaroption allowing duplicatesfixed custom navbar items always being transformed to lowercasefixed navbar generating links to empty pagesaddedconceptsto the default set of links innavbaraddednavbarvaluesallanddefaultreduced I/O churn during HTML post-processingremoved command-line option--dryv0.9.0 - 2022-10-03added support for C++20 conceptsv0.8.2 - 2022-10-01added post-process to inline all local SVGsminor style fixesv0.8.1 - 2022-09-30minor style fixesv0.8.0 - 2022-09-29added config optiongitlab(#13) (@wroyca)added ixx module extension in source patterns (#11) (@wroyca)added support for multi-codepoint emojisimproveddoxygen.exelocation discovery on WindowsimprovedCHANGELOGlocation discoverymoved all poxy assets in the generated HTML tohtml/poxyself-hosted google fonts in generated HTML (instead of requiring additional HTTP requests on page load) (#6)removed ability to override m.css implementationremoved legacy support for reading config options from neighbouring Doxyfilesoverhauled the light thememany minor style fixes and tweaksv0.7.1 - 2022-08-17fixed crash on python <= 3.8 (#9) (@wroyca)v0.7.0 - 2022-08-16fixed some<link>,<meta>and<script>tags not being included in<head>when a file was excluded from post-processingaddedthemecommand-line optionaddedhtml_headerconfig option optionadded automatic generation of github links in changelog when config optiongithubis setadded new light themeadded dynamic switch for dark/light themeremoved text from github icon on navbar (#5) (@wroyca)removed excessive spacing between article sections (#5) (@wroyca)many minor style fixes and tweaksv0.6.1 - 2022-08-16fixed multi-row navbar occluding page content (#3) (@wroyca)v0.6.0 - 2022-08-14fixed malformed error messages in some circumstancesadded builtin C++ standard macros for C++23addedchangelogconfig optionupdated cppreference.com tagfilev0.5.7 - 2022-05-17fixed being able to pass >= 33 threads to Doxygen'sNUM_PROC_THREADSv0.5.6 - 2022-05-14fixed path error when using--dryfixedfriendkeyword sometimes leaking into function return typesadded additional language code block aliasesadded--nocleanupto--helpoutputadded support for C++20'sconstevalkeywordv0.5.5 - 2022-04-16fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)v0.5.4 - 2022-04-15updated m.cssupdated emoji databasev0.5.3 - 2021-12-12fixed Doxygen bug that would sometimes treat keywords likefriendas part of a function's return typeBlacklisted schema 0.7.5 becauseit's brokenv0.5.2 - 2021-11-02fixed over-eager link-replacement for internal#anchorlinksadded command-line options--ppincludeand--ppexcludev0.5.1 - 2021-10-09fixed over-eager link replacement causing text to be deletedv0.5.0 - 2021-09-11fixed a crash during HTML post-processingfixedimplementation_headersnot working when paths use backslashesadded warnings whenimplementation_headersdoesn't match anythingv0.4.5 - 2021-06-08added command-line option--xmlonlyv0.4.3 - 2021-05-31fixed regression in[code_blocks]functionalityfixed minor issues in syntax highlighteradded symbols from doxygen tagfiles to the syntax highlighterminor style tweaksv0.4.1 - 2021-05-30fixed.dirsbeing glommed as source pathsadded config optionscriptsadded config optionstylesheetsadded config optionjqueryaddedcustomthemeadded ability to useHOME.mdas main pageadded additional fix for inline<code>blocksadded.poxy-tocto table-of-contents elementsadded floating page table-of-contentsremoved m.css favicon fallbackmade improvements to thelightanddarkthemesupdated C++ doxygen tagfilev0.4.0 - 2021-05-29added config optionthemeadded version number to CSS and javascript filenames to prevent browser cache issuesaddedPOXY_IMPLEMENTATION_DETAIL(...)magic macroaddedPOXY_IGNORE(...)magic macrofixed alignment of nested images inside detail blocksv0.3.4 - 2021-05-28added basicusingalias detection to syntax highlighteradded missing badges for C++23, 26 and 29v0.3.3 - 2021-05-23fixed sorting of namespace and group membersfixed m.css failing with new versions of doxygen due toDoxyfile.xmladded google structured data to\pagesv0.3.2 - 2021-05-19fixed formatting of<meta>tagsadded config optionauthoradded config optionrobotsadded markup tag[p]added markup tag[center]v0.3.1 - 2021-05-13added config optionmacrosadded command-line option--versionv0.3.0 - 2021-05-09Improved handling of m.css and Doxygen warnings and errorsadded command-line option--doxygenadded command-line option--werroradded markup tag[set_parent_class]added markup tag[add_parent_class]added markup tag[remove_parent_class]added config optionimagesadded config optionexamplesadded ability to specify tagfiles as URIsv0.2.1 - 2021-05-07fixed some minor autolinking issuesv0.2.0 - 2021-05-06added config optionsource_patternsv0.1.2 - 2021-05-02fixed the Z-order of the nav bar being higher than the search overlayaddedNDEBUGto the default set of definesv0.1.1 - 2021-04-26added an additional cleanup step to the HTML postprocessorv0.1.0 - 2021-04-26First public release :tada: