{"id":13496533,"url":"https://github.com/marzer/poxy","last_synced_at":"2025-04-12T15:35:28.608Z","repository":{"id":57454406,"uuid":"350481396","full_name":"marzer/poxy","owner":"marzer","description":"Documentation generator for C++","archived":false,"fork":false,"pushed_at":"2024-12-25T20:30:40.000Z","size":2368,"stargazers_count":142,"open_issues_count":4,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-03T14:11:03.667Z","etag":null,"topics":["c-plus-plus","cpp","doxygen"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/poxy","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marzer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"marzer"}},"created_at":"2021-03-22T20:33:43.000Z","updated_at":"2025-02-15T23:59:33.000Z","dependencies_parsed_at":"2024-01-16T09:56:14.496Z","dependency_job_id":"f62a60d2-968f-48ad-ba69-b248590a78b8","html_url":"https://github.com/marzer/poxy","commit_stats":{"total_commits":137,"total_committers":4,"mean_commits":34.25,"dds":0.03649635036496346,"last_synced_commit":"c61af906891d3b8add4811a2ad8c705a81a5a6f4"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Fpoxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Fpoxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Fpoxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Fpoxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marzer","download_url":"https://codeload.github.com/marzer/poxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590123,"owners_count":21129753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","cpp","doxygen"],"created_at":"2024-07-31T19:01:50.919Z","updated_at":"2025-04-12T15:35:28.555Z","avatar_url":"https://github.com/marzer.png","language":"Python","readme":"# poxy\n\nDocumentation generator for C++ based on Doxygen and [mosra/m.css](https://mcss.mosra.cz/).\n\n[![Sponsor](https://img.shields.io/static/v1?label=sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86\u0026style=flat-square)][sponsor]\n[![Gitter](https://badges.gitter.im/marzer/poxy.svg)][gitter]\n\n-   [Overview](#overview)\n-   [Example](#example)\n-   [Installation](#installation)\n-   [Usage](#usage)\n-   [Config file options](#config-file-options)\n-   [Migrating from Doxygen](#migrating-from-doxygen)\n-   [Why the name \"Poxy\"?](#why-the-name-poxy)\n-   [License and Attribution](#license-and-attribution)\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Overview\n\n[mosra/m.css] is a Doxygen-based documentation generator that significantly improves on Doxygen's default output\nby controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding\na fantastic live search feature. **Poxy** builds upon both by:\n\n-   Moving the configuration out into a TOML file\n-   Preprocessing the Doxygen XML to fix a bunch of Doxygen _~~bugs~~_ quirks\n-   Postprocessing the generated HTML to improve syntax highlighting and add a few other improvements\n-   Allowing source, image and example directories to be recursive or shallow on a per-directory basis\n-   Automatically defining C++ language feature macros based on your project's target C++ version\n-   Automatically integrating the cppreference.com doxygen tagfile\n-   Providing a number of additional built-in doxygen `@alias` commands\n-   Giving more control over the HTML inline using square-bracket `[tags][/tags]`\n-   Adding a switchable light theme\n-   Adding support for C++20 concepts\n-   Self-hosting fonts to reduce external HTTP requests\n-   Inlining SVGs so they can take advantage of [`currentColor`]\n-   Quite a bit more!\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Example\n\nThe homepage + documentation for [toml++] is built using poxy:\n\n-   homepage: [marzer.github.io/tomlplusplus](https://marzer.github.io/tomlplusplus/)\n-   config file: [`poxy.toml`](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml)\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Installation\n\n### Prerequisites:\n\n-   Python 3.7+\n-   Doxygen 1.8.20+ (must be visible on system path)\n\n### Then:\n\n```\npip install poxy\n```\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Usage\n\nPoxy is a command-line application.\n\n```\nusage: poxy [-h] [-v] [--html | --no-html] [--ppinclude \u003cregex\u003e] [--ppexclude \u003cregex\u003e]\n            [--theme {light,dark,custom}] [--threads N] [--version] [--xml | --no-xml]\n            [--werror | --no-werror] [--bug-report] [--git-tags]\n            [--squash-patches | --no-squash-patches] [--min-version \u003cversion\u003e]\n            [config]\n\n  _ __   _____  ___   _\n | '_ \\ / _ \\ \\/ / | | |\n | |_) | (_) \u003e  \u003c| |_| |\n | .__/ \\___/_/\\_\\\\__, |\n | |               __/ |\n |_|              |___/  v0.17.0 - github.com/marzer/poxy\n\nGenerate fancy C++ documentation.\n\npositional arguments:\n  config                path to poxy.toml or a directory containing it (default: .)\n\noptions:\n  -h, --help            show this help message and exit\n  -v, --verbose         enable very noisy diagnostic output\n  --html, --no-html     specify whether HTML output is required\n  --ppinclude \u003cregex\u003e   pattern matching HTML file names to post-process (default: all)\n  --ppexclude \u003cregex\u003e   pattern matching HTML file names to exclude from post-processing (default: None)\n  --theme {light,dark,custom}\n                        sets the default visual theme (default: read from config)\n  --threads N           set the number of threads to use (default: automatic)\n  --version             print the version and exit\n  --xml, --no-xml       specify whether XML output is required\n  --werror, --no-werror\n                        treat warnings as errors (default: read from config)\n  --bug-report          captures all output in a zip file for easier bug reporting.\n  --git-tags            add git-tag-based semver version switcher to the generated HTML\n  --squash-patches, --no-squash-patches\n                        when using --git-tags and two version tags differ by a patch number,\n                        generate docs for the highest one only (default: True)\n  --min-version \u003cversion\u003e\n                        sets the minimum version number to emit when using --git-tags,\n                        or a negative integer to mean \"the last N versions\". (default: None)\n```\n\nThe basic three-step to using Poxy is similar to Doxygen:\n\n1. Create your `poxy.toml` (Poxy's answer to the `Doxyfile`)\n2. Invoke Poxy on it: `poxy path/to/poxy.toml` (or simply `poxy` if the cwd contains the config file)\n3. See your HTML documentation `\u003ccwd\u003e/html`\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Config file options\n\nFor a self-contained `poxy.toml` example to copy and paste from,\nsee [the one used by toml++](https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml).\n\nFor a full list of options, with full descriptions, schemas and usage examples, see the [Configuration options] wiki page.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Migrating from Doxygen\n\nGenerally the relevant `Doxyfile` options will have a corresponding `poxy.toml` option\n(or be replaced by something more specific) so migration is largely a transcription and box-ticking exercise,\nthough there are a few gotchas:\n\n#### **⚠\u0026#xFE0F; The majority of Doxygen's options are controlled by Poxy**\n\nMany of Doxygen's various knobs and switches are manually overridden by Poxy, and are not configurable.\n**This is intentional!** Doxygen tends to break in hilarious and fantastic ways from one release to the next;\nreducing it to a very 'locked-down' back-end minimizes the damage future regressions can do, allowing me to\nkeep most debugging python-side.\n\nIf there is some Doxygen feature you would like exposed in Poxy, please create a [feature request].\n\n#### **⚠\u0026#xFE0F; All relative input paths are relative to the config file, _not_ CWD**\n\nThis is in contrast to Doxygen, which has all paths be relative to the Doxygen process' current working directory\nregardless of where the Doxyfile was. I've always personally found that to be nothing but a source of error,\nso Poxy does away with it.\n\n#### **⚠\u0026#xFE0F; Output is always emitted to CWD**\n\nPoxy always emits HTML to `\u003ccwd\u003e/html` and XML to `\u003ccwd\u003e/xml`. You cannot use your config file to specify where any\noutput will be placed - use your command-line environment for this purpose instead by changing the CWD.\nThis is to eliminate nasty surprises brought on by goofy config file decisions and help with portability.\n\n#### **⚠\u0026#xFE0F; Poxy config files are self-contained**\n\nThere is no equivalent to Doxygen's `@INCLUDE`. If your project is structured in such a way that a\nmulti-level Doxyfile hierarchy is necessary, Poxy isn't for you.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Why the name \"Poxy\"?\n\nOriginally it was simply called \"dox\", but there's already a C++ documentation project with that name,\nso I smashed \"python\" and \"dox\" together and this is what I came up with.\n\nAlso \"poxy\" can be slang for cheap, inferior, poor quality, etc., which I thought was funny.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## License and Attribution\n\nThis project is published under the terms of the [MIT license](https://github.com/marzer/poxy/blob/main/LICENSE.txt).\n\nSignificant credit must go to Vladimír Vondruš ([mosra]) and his amazing [m.css] Doxygen theme.\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)\n(which can also be found in the installed python package).\n\n[m.css]: https://mcss.mosra.cz/documentation/doxygen/\n[mosra]: https://github.com/mosra\n[mosra/m.css]: https://mcss.mosra.cz/documentation/doxygen/\n[toml++]: https://marzer.github.io/tomlplusplus/\n[c++ feature test macros]: https://en.cppreference.com/w/cpp/feature_test\n[configuration options]: https://github.com/marzer/poxy/wiki/Configuration-options\n[feature request]: https://github.com/marzer/poxy/issues/new\n[`currentcolor`]: https://gomakethings.com/currentcolor-and-svgs\n[gitter]: https://gitter.im/marzer/poxy\n[sponsor]: https://github.com/sponsors/marzer\n","funding_links":["https://github.com/sponsors/marzer"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzer%2Fpoxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarzer%2Fpoxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzer%2Fpoxy/lists"}