| Name | poxy JSON |
| Version |
0.17.0
JSON |
| download |
| home_page | None |
| Summary | Documentation generator for C++. |
| upload_time | 2024-04-21 13:49:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
c++
doxygen
documentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# poxy
Documentation generator for C++ based on Doxygen and [mosra/m.css](https://mcss.mosra.cz/).
[][sponsor]
[][gitter]
- [Overview](#overview)
- [Example](#example)
- [Installation](#installation)
- [Usage](#usage)
- [Config file options](#config-file-options)
- [Migrating from Doxygen](#migrating-from-doxygen)
- [Why the name "Poxy"?](#why-the-name-poxy)
- [License and Attribution](#license-and-attribution)
<br><br>
## 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!
<br><br>
## Example
The homepage + documentation for [toml++] is built using poxy:
- homepage: [marzer.github.io/tomlplusplus](https://marzer.github.io/tomlplusplus/)
- config file: [`poxy.toml`](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml)
<br><br>
## Installation
### Prerequisites:
- Python 3.7+
- Doxygen 1.8.20+ (must be visible on system path)
### Then:
```
pip install poxy
```
<br><br>
## 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`
<br><br>
## Config file options
For a self-contained `poxy.toml` example to copy and paste from,
see [the one used by toml++](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml).
For a full list of options, with full descriptions, schemas and usage examples, see the [Configuration options] wiki page.
<br><br>
## 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.
<br><br>
## 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.
<br><br>
## License and Attribution
This project is published under the terms of the [MIT license](https://github.com/marzer/poxy/blob/main/LICENSE.txt).
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](https://github.com/marzer/poxy/blob/main/poxy/data/m.css/COPYING)
(which can also be found in the installed python package).
[m.css]: https://mcss.mosra.cz/documentation/doxygen/
[mosra]: https://github.com/mosra
[mosra/m.css]: https://mcss.mosra.cz/documentation/doxygen/
[toml++]: https://marzer.github.io/tomlplusplus/
[c++ feature test macros]: https://en.cppreference.com/w/cpp/feature_test
[configuration options]: https://github.com/marzer/poxy/wiki/Configuration-options
[feature request]: https://github.com/marzer/poxy/issues/new
[`currentcolor`]: https://gomakethings.com/currentcolor-and-svgs
[gitter]: https://gitter.im/marzer/poxy
[sponsor]: https://github.com/sponsors/marzer
# 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](https://en.cppreference.com/w/cpp/named_req)
- 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](https://github.com/keleshev/schema/issues/272)
## 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:
Raw data
{
"_id": null,
"home_page": null,
"name": "poxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "c++, doxygen, documentation",
"author": null,
"author_email": "Mark Gillard <mark.gillard@outlook.com.au>",
"download_url": "https://files.pythonhosted.org/packages/51/99/0740c09864fc51c433b3afbbe69b74fb6e71e9a8eb608cc77c4571b9b127/poxy-0.17.0.tar.gz",
"platform": null,
"description": "# poxy\r\n\r\nDocumentation generator for C++ based on Doxygen and [mosra/m.css](https://mcss.mosra.cz/).\r\n\r\n[][sponsor]\r\n[][gitter]\r\n\r\n- [Overview](#overview)\r\n- [Example](#example)\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n- [Config file options](#config-file-options)\r\n- [Migrating from Doxygen](#migrating-from-doxygen)\r\n- [Why the name \"Poxy\"?](#why-the-name-poxy)\r\n- [License and Attribution](#license-and-attribution)\r\n\r\n<br><br>\r\n\r\n## Overview\r\n\r\n[mosra/m.css] is a Doxygen-based documentation generator that significantly improves on Doxygen's default output\r\nby controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding\r\na fantastic live search feature. **Poxy** builds upon both by:\r\n\r\n- Moving the configuration out into a TOML file\r\n- Preprocessing the Doxygen XML to fix a bunch of Doxygen _~~bugs~~_ quirks\r\n- Postprocessing the generated HTML to improve syntax highlighting and add a few other improvements\r\n- Allowing source, image and example directories to be recursive or shallow on a per-directory basis\r\n- Automatically defining C++ language feature macros based on your project's target C++ version\r\n- Automatically integrating the cppreference.com doxygen tagfile\r\n- Providing a number of additional built-in doxygen `@alias` commands\r\n- Giving more control over the HTML inline using square-bracket `[tags][/tags]`\r\n- Adding a switchable light theme\r\n- Adding support for C++20 concepts\r\n- Self-hosting fonts to reduce external HTTP requests\r\n- Inlining SVGs so they can take advantage of [`currentColor`]\r\n- Quite a bit more!\r\n\r\n<br><br>\r\n\r\n## Example\r\n\r\nThe homepage + documentation for [toml++] is built using poxy:\r\n\r\n- homepage: [marzer.github.io/tomlplusplus](https://marzer.github.io/tomlplusplus/)\r\n- config file: [`poxy.toml`](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml)\r\n\r\n<br><br>\r\n\r\n## Installation\r\n\r\n### Prerequisites:\r\n\r\n- Python 3.7+\r\n- Doxygen 1.8.20+ (must be visible on system path)\r\n\r\n### Then:\r\n\r\n```\r\npip install poxy\r\n```\r\n\r\n<br><br>\r\n\r\n## Usage\r\n\r\nPoxy is a command-line application.\r\n\r\n```\r\nusage: poxy [-h] [-v] [--html | --no-html] [--ppinclude <regex>] [--ppexclude <regex>]\r\n [--theme {light,dark,custom}] [--threads N] [--version] [--xml | --no-xml]\r\n [--werror | --no-werror] [--bug-report] [--git-tags]\r\n [--squash-patches | --no-squash-patches] [--min-version <version>]\r\n [config]\r\n\r\n _ __ _____ ___ _\r\n | '_ \\ / _ \\ \\/ / | | |\r\n | |_) | (_) > <| |_| |\r\n | .__/ \\___/_/\\_\\\\__, |\r\n | | __/ |\r\n |_| |___/ v0.17.0 - github.com/marzer/poxy\r\n\r\nGenerate fancy C++ documentation.\r\n\r\npositional arguments:\r\n config path to poxy.toml or a directory containing it (default: .)\r\n\r\noptions:\r\n -h, --help show this help message and exit\r\n -v, --verbose enable very noisy diagnostic output\r\n --html, --no-html specify whether HTML output is required\r\n --ppinclude <regex> pattern matching HTML file names to post-process (default: all)\r\n --ppexclude <regex> pattern matching HTML file names to exclude from post-processing (default: None)\r\n --theme {light,dark,custom}\r\n sets the default visual theme (default: read from config)\r\n --threads N set the number of threads to use (default: automatic)\r\n --version print the version and exit\r\n --xml, --no-xml specify whether XML output is required\r\n --werror, --no-werror\r\n treat warnings as errors (default: read from config)\r\n --bug-report captures all output in a zip file for easier bug reporting.\r\n --git-tags add git-tag-based semver version switcher to the generated HTML\r\n --squash-patches, --no-squash-patches\r\n when using --git-tags and two version tags differ by a patch number,\r\n generate docs for the highest one only (default: True)\r\n --min-version <version>\r\n sets the minimum version number to emit when using --git-tags,\r\n or a negative integer to mean \"the last N versions\". (default: None)\r\n```\r\n\r\nThe basic three-step to using Poxy is similar to Doxygen:\r\n\r\n1. Create your `poxy.toml` (Poxy's answer to the `Doxyfile`)\r\n2. Invoke Poxy on it: `poxy path/to/poxy.toml` (or simply `poxy` if the cwd contains the config file)\r\n3. See your HTML documentation `<cwd>/html`\r\n\r\n<br><br>\r\n\r\n## Config file options\r\n\r\nFor a self-contained `poxy.toml` example to copy and paste from,\r\nsee [the one used by toml++](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml).\r\n\r\nFor a full list of options, with full descriptions, schemas and usage examples, see the [Configuration options] wiki page.\r\n\r\n<br><br>\r\n\r\n## Migrating from Doxygen\r\n\r\nGenerally the relevant `Doxyfile` options will have a corresponding `poxy.toml` option\r\n(or be replaced by something more specific) so migration is largely a transcription and box-ticking exercise,\r\nthough there are a few gotchas:\r\n\r\n#### **\u26a0️ The majority of Doxygen's options are controlled by Poxy**\r\n\r\nMany of Doxygen's various knobs and switches are manually overridden by Poxy, and are not configurable.\r\n**This is intentional!** Doxygen tends to break in hilarious and fantastic ways from one release to the next;\r\nreducing it to a very 'locked-down' back-end minimizes the damage future regressions can do, allowing me to\r\nkeep most debugging python-side.\r\n\r\nIf there is some Doxygen feature you would like exposed in Poxy, please create a [feature request].\r\n\r\n#### **\u26a0️ All relative input paths are relative to the config file, _not_ CWD**\r\n\r\nThis is in contrast to Doxygen, which has all paths be relative to the Doxygen process' current working directory\r\nregardless of where the Doxyfile was. I've always personally found that to be nothing but a source of error,\r\nso Poxy does away with it.\r\n\r\n#### **\u26a0️ Output is always emitted to CWD**\r\n\r\nPoxy always emits HTML to `<cwd>/html` and XML to `<cwd>/xml`. You cannot use your config file to specify where any\r\noutput will be placed - use your command-line environment for this purpose instead by changing the CWD.\r\nThis is to eliminate nasty surprises brought on by goofy config file decisions and help with portability.\r\n\r\n#### **\u26a0️ Poxy config files are self-contained**\r\n\r\nThere is no equivalent to Doxygen's `@INCLUDE`. If your project is structured in such a way that a\r\nmulti-level Doxyfile hierarchy is necessary, Poxy isn't for you.\r\n\r\n<br><br>\r\n\r\n## Why the name \"Poxy\"?\r\n\r\nOriginally it was simply called \"dox\", but there's already a C++ documentation project with that name,\r\nso I smashed \"python\" and \"dox\" together and this is what I came up with.\r\n\r\nAlso \"poxy\" can be slang for cheap, inferior, poor quality, etc., which I thought was funny.\r\n\r\n<br><br>\r\n\r\n## License and Attribution\r\n\r\nThis project is published under the terms of the [MIT license](https://github.com/marzer/poxy/blob/main/LICENSE.txt).\r\n\r\nSignificant credit must go to Vladim\u00edr Vondru\u0161 ([mosra]) and his amazing [m.css] Doxygen theme.\r\nPoxy bundles a fork of m.css, used per the [MIT/Expat license](https://github.com/marzer/poxy/blob/main/poxy/data/m.css/COPYING)\r\n(which can also be found in the installed python package).\r\n\r\n[m.css]: https://mcss.mosra.cz/documentation/doxygen/\r\n[mosra]: https://github.com/mosra\r\n[mosra/m.css]: https://mcss.mosra.cz/documentation/doxygen/\r\n[toml++]: https://marzer.github.io/tomlplusplus/\r\n[c++ feature test macros]: https://en.cppreference.com/w/cpp/feature_test\r\n[configuration options]: https://github.com/marzer/poxy/wiki/Configuration-options\r\n[feature request]: https://github.com/marzer/poxy/issues/new\r\n[`currentcolor`]: https://gomakethings.com/currentcolor-and-svgs\r\n[gitter]: https://gitter.im/marzer/poxy\r\n[sponsor]: https://github.com/sponsors/marzer\r\n\r\n# Changelog\r\n\r\n## v0.17.0 - 2024-04-21\r\n\r\n- added arguments `--min-version` and `--squash-patches` for more control over `--git-tags` mode\r\n\r\n## v0.16.0 - 2024-01-28\r\n\r\n- added multi-version mode argument `--git-tags`\r\n- added colour to output\r\n\r\n## v0.15.0 - 2023-12-08\r\n\r\n- added config option `main_page` (a.k.a. `USE_MDFILE_AS_MAINPAGE`)\r\n- fixed searching for `CHANGELOG` too far up the directory heirarchy (now stops when a `.git` folder is encountered)\r\n\r\n## v0.14.0 - 2023-11-25\r\n\r\n- added the use of `*` wildcards in `implementation_headers`\r\n\r\n## v0.13.9 - 2023-09-10\r\n\r\n- fixed crash on Doxygen <= 1.8.17 (#33) (@tim-janik)\r\n\r\n## v0.13.8 - 2023-09-09\r\n\r\n- fixed regression for Python <= 3.8 (#32) (@tim-janik)\r\n\r\n## v0.13.7 - 2023-08-17\r\n\r\n- fixed minor syntax highlighting issues\r\n\r\n## v0.13.6 - 2023-08-10\r\n\r\n- update m.css to fix libgs.so lookup (#31) (@wroyca, @mosra)\r\n\r\n## v0.13.5 - 2023-08-09\r\n\r\n- fixed `--bug-report` regression (#29) (@wroyca)\r\n\r\n## v0.13.4 - 2023-08-06\r\n\r\n- fixed excessive `template<>` noise in details views\r\n\r\n## v0.13.3 - 2023-08-01\r\n\r\n- fixed floating TOCs sometimes clipping off the bottom of the screen when the viewport was vertically narrow\r\n\r\n## v0.13.2 - 2023-07-31\r\n\r\n- fixed doxygen's `@ref` links to `#id` anchors on the same page being treated as external links\r\n- added auto-linking for C++ [named requirements](https://en.cppreference.com/w/cpp/named_req)\r\n- minor style fixes\r\n\r\n## v0.13.1 - 2023-07-29\r\n\r\n- fixed crash regression with Doxygen 1.9.7\r\n- fixed issues with \\[tag\\] substitution\r\n- minor style fixes\r\n\r\n## v0.13.0 - 2023-07-28\r\n\r\n- migrated to `pyproject.toml`\r\n- fixed footer being off-center (#24) (@wroyca)\r\n- fixed redundant `auto` in trailing return types (#26) (@wroyca)\r\n- added config option `sponsor`\r\n- added config option `twitter`\r\n\r\n## v0.12.7 - 2023-07-27\r\n\r\n- allowed the use of square-bracket \\[tags\\] in more places\r\n\r\n## v0.12.6 - 2023-07-25\r\n\r\n- fixed overlong `template<>` lines in summary views\r\n- fixed function parameter names greedily wrapping in details tables\r\n\r\n## v0.12.5 - 2023-07-20\r\n\r\n- fixed overlong `template<>` lines in page headers (they now wrap)\r\n\r\n## v0.12.4 - 2023-03-23\r\n\r\n- fixed changelog not auto-linking with some versions of Doxygen\r\n\r\n## v0.12.3 - 2023-02-09\r\n\r\n- fixed backwards-incompatible use of a newer `argparse` feature on Python <= 3.8 (#20) (@fwerner)\r\n\r\n## v0.12.2 - 2023-02-08\r\n\r\n- switched default TOML lib to `tomli`\r\n\r\n## v0.12.1 - 2022-11-22\r\n\r\n- fixed `github` and `gitlab` config options not accepting periods (`.`)\r\n\r\n## v0.12.0 - 2022-11-13\r\n\r\n- fixed `AttributeError` during XML post-processing (#17) (@wroyca)\r\n- added command-line option `--bug-report`\r\n- improved diagnostic text in some areas\r\n\r\n## v0.11.1 - 2022-10-23\r\n\r\n- fixed crash when using `<a>` tags in navbar\r\n\r\n## v0.11.0 - 2022-10-21\r\n\r\n- added syntax highlighting for functions\r\n- improved syntax highlighting of typenames\r\n\r\n## v0.10.2 - 2022-10-16\r\n\r\n- fixed crash when tagfile is disabled\r\n- fixed a few syntax highlighting edge-cases\r\n- fixed non-determinism in XML output formatting\r\n- improved performance of syntax highlighting post-process\r\n- minor style fixes\r\n\r\n## v0.10.1 - 2022-10-15\r\n\r\n- minor style fixes\r\n\r\n## v0.10.0 - 2022-10-14\r\n\r\n- fixed `static` keyword sometimes appearing twice on variables\r\n- fixed `constexpr` keyword sometimes leaking into variable type\r\n- fixed newer versions of pygments adding unnecessary markup to whitespace\r\n- fixed malformed trailing return types in some circumstances\r\n- fixed changelog page sometimes not having a table-of-contents\r\n- added support for C++20's `constinit`\r\n- added fallback to `tomllib` or `tomli` if `pytomlpp` is not available\r\n- added command-line options `--html`, `--no-html`\r\n- added command-line options `--xml`, `--no-xml`\r\n- added command-line option `--no-werror`\r\n- added `CHANGES` to the set of candidate changelog filenames\r\n- deprecated command-line option `--xmlonly`\r\n- removed command-line option `--doxygen`\r\n\r\n## v0.9.1 - 2022-10-04\r\n\r\n- fixed SVG inlining not preserving original image class attributes\r\n- fixed `ValueError` when reading some SVG files\r\n- fixed `navbar` option allowing duplicates\r\n- fixed custom navbar items always being transformed to lowercase\r\n- fixed navbar generating links to empty pages\r\n- added `concepts` to the default set of links in `navbar`\r\n- added `navbar` values `all` and `default`\r\n- reduced I/O churn during HTML post-processing\r\n- removed command-line option `--dry`\r\n\r\n## v0.9.0 - 2022-10-03\r\n\r\n- added support for C++20 concepts\r\n\r\n## v0.8.2 - 2022-10-01\r\n\r\n- added post-process to inline all local SVGs\r\n- minor style fixes\r\n\r\n## v0.8.1 - 2022-09-30\r\n\r\n- minor style fixes\r\n\r\n## v0.8.0 - 2022-09-29\r\n\r\n- added config option `gitlab` (#13) (@wroyca)\r\n- added ixx module extension in source patterns (#11) (@wroyca)\r\n- added support for multi-codepoint emojis\r\n- improved `doxygen.exe` location discovery on Windows\r\n- improved `CHANGELOG` location discovery\r\n- moved all poxy assets in the generated HTML to `html/poxy`\r\n- self-hosted google fonts in generated HTML (instead of requiring additional HTTP requests on page load) (#6)\r\n- removed ability to override m.css implementation\r\n- removed legacy support for reading config options from neighbouring Doxyfiles\r\n- overhauled the light theme\r\n- many minor style fixes and tweaks\r\n\r\n## v0.7.1 - 2022-08-17\r\n\r\n- fixed crash on python <= 3.8 (#9) (@wroyca)\r\n\r\n## v0.7.0 - 2022-08-16\r\n\r\n- fixed some `<link>`, `<meta>` and `<script>` tags not being included in `<head>` when a file was excluded from post-processing\r\n- added `theme` command-line option\r\n- added `html_header` config option option\r\n- added automatic generation of github links in changelog when config option `github` is set\r\n- added new light theme\r\n- added dynamic switch for dark/light theme\r\n- removed text from github icon on navbar (#5) (@wroyca)\r\n- removed excessive spacing between article sections (#5) (@wroyca)\r\n- many minor style fixes and tweaks\r\n\r\n## v0.6.1 - 2022-08-16\r\n\r\n- fixed multi-row navbar occluding page content (#3) (@wroyca)\r\n\r\n## v0.6.0 - 2022-08-14\r\n\r\n- fixed malformed error messages in some circumstances\r\n- added builtin C++ standard macros for C++23\r\n- added `changelog` config option\r\n- updated cppreference.com tagfile\r\n\r\n## v0.5.7 - 2022-05-17\r\n\r\n- fixed being able to pass >= 33 threads to Doxygen's `NUM_PROC_THREADS`\r\n\r\n## v0.5.6 - 2022-05-14\r\n\r\n- fixed path error when using `--dry`\r\n- fixed `friend` keyword sometimes leaking into function return types\r\n- added additional language code block aliases\r\n- added `--nocleanup` to `--help` output\r\n- added support for C++20's `consteval` keyword\r\n\r\n## v0.5.5 - 2022-04-16\r\n\r\n- fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)\r\n\r\n## v0.5.4 - 2022-04-15\r\n\r\n- updated m.css\r\n- updated emoji database\r\n\r\n## v0.5.3 - 2021-12-12\r\n\r\n- fixed Doxygen bug that would sometimes treat keywords like `friend` as part of a function's return type\r\n- Blacklisted schema 0.7.5 because [it's broken](https://github.com/keleshev/schema/issues/272)\r\n\r\n## v0.5.2 - 2021-11-02\r\n\r\n- fixed over-eager link-replacement for internal `#anchor` links\r\n- added command-line options `--ppinclude` and `--ppexclude`\r\n\r\n## v0.5.1 - 2021-10-09\r\n\r\n- fixed over-eager link replacement causing text to be deleted\r\n\r\n## v0.5.0 - 2021-09-11\r\n\r\n- fixed a crash during HTML post-processing\r\n- fixed `implementation_headers` not working when paths use backslashes\r\n- added warnings when `implementation_headers` doesn't match anything\r\n\r\n## v0.4.5 - 2021-06-08\r\n\r\n- added command-line option `--xmlonly`\r\n\r\n## v0.4.3 - 2021-05-31\r\n\r\n- fixed regression in `[code_blocks]` functionality\r\n- fixed minor issues in syntax highlighter\r\n- added symbols from doxygen tagfiles to the syntax highlighter\r\n- minor style tweaks\r\n\r\n## v0.4.1 - 2021-05-30\r\n\r\n- fixed `.dirs` being glommed as source paths\r\n- added config option `scripts`\r\n- added config option `stylesheets`\r\n- added config option `jquery`\r\n- added `custom` theme\r\n- added ability to use `HOME.md` as main page\r\n- added additional fix for inline `<code>` blocks\r\n- added `.poxy-toc` to table-of-contents elements\r\n- added floating page table-of-contents\r\n- removed m.css favicon fallback\r\n- made improvements to the `light` and `dark` themes\r\n- updated C++ doxygen tagfile\r\n\r\n## v0.4.0 - 2021-05-29\r\n\r\n- added config option `theme`\r\n- added version number to CSS and javascript filenames to prevent browser cache issues\r\n- added `POXY_IMPLEMENTATION_DETAIL(...)` magic macro\r\n- added `POXY_IGNORE(...)` magic macro\r\n- fixed alignment of nested images inside detail blocks\r\n\r\n## v0.3.4 - 2021-05-28\r\n\r\n- added basic `using` alias detection to syntax highlighter\r\n- added missing badges for C++23, 26 and 29\r\n\r\n## v0.3.3 - 2021-05-23\r\n\r\n- fixed sorting of namespace and group members\r\n- fixed m.css failing with new versions of doxygen due to `Doxyfile.xml`\r\n- added google structured data to `\\pages`\r\n\r\n## v0.3.2 - 2021-05-19\r\n\r\n- fixed formatting of `<meta>` tags\r\n- added config option `author`\r\n- added config option `robots`\r\n- added markup tag `[p]`\r\n- added markup tag `[center]`\r\n\r\n## v0.3.1 - 2021-05-13\r\n\r\n- added config option `macros`\r\n- added command-line option `--version`\r\n\r\n## v0.3.0 - 2021-05-09\r\n\r\n- Improved handling of m.css and Doxygen warnings and errors\r\n- added command-line option `--doxygen`\r\n- added command-line option `--werror`\r\n- added markup tag `[set_parent_class]`\r\n- added markup tag `[add_parent_class]`\r\n- added markup tag `[remove_parent_class]`\r\n- added config option `images`\r\n- added config option `examples`\r\n- added ability to specify tagfiles as URIs\r\n\r\n## v0.2.1 - 2021-05-07\r\n\r\n- fixed some minor autolinking issues\r\n\r\n## v0.2.0 - 2021-05-06\r\n\r\n- added config option `source_patterns`\r\n\r\n## v0.1.2 - 2021-05-02\r\n\r\n- fixed the Z-order of the nav bar being higher than the search overlay\r\n- added `NDEBUG` to the default set of defines\r\n\r\n## v0.1.1 - 2021-04-26\r\n\r\n- added an additional cleanup step to the HTML postprocessor\r\n\r\n## v0.1.0 - 2021-04-26\r\n\r\nFirst public release :tada:\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Documentation generator for C++.",
"version": "0.17.0",
"project_urls": {
"Funding": "https://github.com/sponsors/marzer",
"Source": "https://github.com/marzer/poxy",
"Tracker": "https://github.com/marzer/poxy/issues"
},
"split_keywords": [
"c++",
" doxygen",
" documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a8d3c42431ea10e0c1e437d2c7d0435a789299b5aab7b3d456a40ca197de054d",
"md5": "153cdb9dbf9c5086cd6a2200aab720eb",
"sha256": "0ad2f2cdc240e3ea3191bddb5b55e586db834b16181b1f34d511cfc8d9e256f9"
},
"downloads": -1,
"filename": "poxy-0.17.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "153cdb9dbf9c5086cd6a2200aab720eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 847867,
"upload_time": "2024-04-21T13:49:13",
"upload_time_iso_8601": "2024-04-21T13:49:13.636775Z",
"url": "https://files.pythonhosted.org/packages/a8/d3/c42431ea10e0c1e437d2c7d0435a789299b5aab7b3d456a40ca197de054d/poxy-0.17.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51990740c09864fc51c433b3afbbe69b74fb6e71e9a8eb608cc77c4571b9b127",
"md5": "5f5dea075a26eb89ce39c48fe621c9ed",
"sha256": "224c3f2722ba592a6f23108b1435b89718e6c42554034bd265b2ba67037f77dc"
},
"downloads": -1,
"filename": "poxy-0.17.0.tar.gz",
"has_sig": false,
"md5_digest": "5f5dea075a26eb89ce39c48fe621c9ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 769436,
"upload_time": "2024-04-21T13:49:16",
"upload_time_iso_8601": "2024-04-21T13:49:16.723626Z",
"url": "https://files.pythonhosted.org/packages/51/99/0740c09864fc51c433b3afbbe69b74fb6e71e9a8eb608cc77c4571b9b127/poxy-0.17.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-21 13:49:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "marzer",
"github_not_found": true,
"lcname": "poxy"
}
