Documentation generator for C++ based on Doxygen and mosra/m.css.

Mark Gillard

Last update: Dec 7, 2022

Related tags

Overview

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]
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
Doxygen (preferably a version from this decade, though most will be OK)

Then:

pip install poxy

Usage

Poxy is a command-line application.

poxy [-h] [-v] [--dry] [--threads ] [--m.css ] [--doxygen ] [--werror] [--version] [config]

Generate fancy C++ documentation.

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

optional arguments:
  -h, --help        show this help message and exit
  -v, --verbose     enable very noisy diagnostic output
  --dry             do a 'dry run' only, stopping after emitting the effective Doxyfile
  --threads      set the number of threads to use (default: automatic)
  --m.css     specify the version of m.css to use (default: uses the bundled one)
  --doxygen   specify the Doxygen executable to use (default: finds Doxygen on system path)
  --werror          always treat warnings as errors regardless of config file settings
  --version         print the version and exit

The basic three-step to using Poxy is similar to Doxygen:

Create your poxy.toml (Poxy's answer to the Doxyfile)
Invoke Poxy on it: poxy path/to/poxy.toml (or simply poxy if the cwd contains the config file)
See your HTML documentation /html

ℹ️ If there exists a Doxyfile or Doxyfile-mcss in the same directory as your poxy.toml it will be loaded first, then the Poxy overrides applied on top of it. Otherwise a 'default' Doxyfile is used as the base.

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

Very few of the configurable options from the Doxyfile remain untouched by Poxy. This is intentional; m.css is opinionated, and Poxy even moreso. There are a few instances where information can flow from a Doxyfile to Poxy, but these situations are few, and all are documented explicitly on the Configuration options wiki page.

**⚠️ 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 the output html to /html. This is largely to simplify the HTML post-process step.

⚠️ Poxy config files are self-contained

There is no equivalent to Doxygen's @INCLUDE. If your project is structured in such a way that an N-levels-deep 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 framework. Poxy bundles a fork of m.css, used per the MIT/Expat license (which can also be found in the installed python package).

Comments

Remove excessive padding and text in github icon

see: https://github.com/marzer/poxy/pull/5#issuecomment-1236397268

~The padding is excessively large for article sections. Since I'm not sure if this was intended or if it's a slight shape defect, I thought it best to open this up for investigation:~

(main) margin-top: 4rem | (patch) margin-top: 2rem :-------------------------:|:-------------------------: |

opened by wroyca 26
Help to package on Debian

Hi, I am working to package this module into Debian, I just want to confirm it here: There is misk>=0.7.0 in requirements.txt, the misk is this misk? Because the misk does not come into Debian also,if so, I have to package it first, thanks.

opened by yuzibo 11

GitHub CIs no longer work with v0.7.0

GitHub CIs are still using Python 3.8, which results in incompatibility with v0.7.0. It seems to have been missed by Poxy CI since it never ran Poxy itself - the tests are never used.

Traceback (most recent call last):
  File "/usr/local/bin/poxy", line 5, in <module>
    from poxy.main import main
  File "/usr/local/lib/python3.8/dist-packages/poxy/main.py", line 1[7](https://github.com/wroyca/rune/runs/8239827362?check_suite_focus=true#step:4:8), in <module>
    from . import css
  File "/usr/local/lib/python3.[8](https://github.com/wroyca/rune/runs/8239827362?check_suite_focus=true#step:4:9)/dist-packages/poxy/css.py", line 28, in <module>
    def resolve_imports(text, cwd=None, mcss_dir = None) -> tuple[str, bool]:
TypeError: 'type' object is not subscriptable

opened by wroyca 11

AssertionError when C++20 Concepts are present

MCSS, specifically the mcss fork that Poxy uses (the issues tab isn't present on the fork), compares each fundamental element type against a list (doxygen.py, line 3222) including struct, enum, etc. As concept isn't present, the chain of comparisons ends up at the else condition, which simply asserts False and crashes the entire documentation generation process.

I would appreciate concept generation being added, but I'm also happy for the else condition to simply ignore unknown element types (generating a warning instead of asserting False).

opened by jake-arkinstall 9

Poxy doesn't update submodule(s)

We should consider adding git submodule update --recursive --init to setup.py otherwise users might get an unexpected surprise

Traceback (most recent call last):
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python38\lib\site-packages\poxy-0.7.1-py3.8.egg\poxy\main.py", line 160, in main
    run(
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python38\lib\site-packages\poxy-0.7.1-py3.8.egg\poxy\run.py", line 1146, in run
    with project.Context(
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python38\lib\site-packages\poxy-0.7.1-py3.8.egg\poxy\project.py", line 1264, in __init__
    mcss_dir = find_mcss_dir()
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python38\lib\site-packages\poxy-0.7.1-py3.8.egg\poxy\utils.py", line 149, in find_mcss_dir
    assert_existing_directory(_mcss_dir)
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python38\lib\site-packages\misk\functions.py", line 150, in assert_existing_directory
    raise Exception(f'{path} did not exist or was not a directory')
Exception: C:\Users\wroy\AppData\Local\Programs\Python\Python38\Lib\site-packages\poxy-0.7.1-py3.8.egg\poxy\data\m.css did not exist or was not a directory

opened by wroyca 8

Dynamic switching between light + dark themes

Per title. Discussed in #5.

An implication of this is that the m.css light theme looks quite different from the dark one (i.e. it's not just a pallette swap); for a dynamic switch to make visual sense a new light theme is necessary, one that is a pixel-perfect match for the dark one.

(The m.css light theme is quite nice, though, so I'd still keep it under a different name).
enhancement

opened by marzer 5

m.css uses the wrong path for python

Post-processing XML files
Compiling regexes
Generating HTML files with m.css
m.css failed!
m.css stderr:
    Python was not found; run without arguments to install from the Microsoft Store, or disable this shortcut from Settings > Manage App Execution Aliases.

Nothing like our beloved Microsoft to break things, right? why, oh, why is Microsoft trying to shove the Microsoft Store version of Python down our throats? anyway :

*************

Traceback (most recent call last):
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python311\Lib\site-packages\poxy\main.py", line 327, in main
    run(
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python311\Lib\site-packages\poxy\run.py", line 1644, in run
    run_mcss(context)
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python311\Lib\site-packages\poxy\run.py", line 1546, in run_mcss
    run_python_script(
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python311\Lib\site-packages\misk\functions.py", line 331, in run_python_script
    return subprocess.run(
           ^^^^^^^^^^^^^^^
  File "C:\Users\wroy\AppData\Local\Programs\Python\Python311\Lib\subprocess.py", line 569, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['py', 'C:\\Users\\wroy\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\poxy\\data\\m.css\\documentation\\doxygen.py', 'C:\\Users\\wroy\\AppData\\Local\\Temp\\poxy\\C_Users_wroy_Desktop_echo_docs\\conf.py', '--no-doxygen', '--sort-globbed-files']' returned non-zero exit status 9009.

*************

poxy_bug_report.zip

bug

opened by wroyca 4

AttributeError: The Revenge

While trying to generate gnome-builder (I know, I know, I only have myself to blame for parsing a C project :sweat: ), I came across this post-processing error:

Post-processing XML files
Traceback (most recent call last):
  File "/home/wroy/.local/lib/python3.11/site-packages/poxy/main.py", line 226, in main
    run(
  File "/home/wroy/.local/lib/python3.11/site-packages/poxy/run.py", line 1619, in run
    postprocess_xml(context)
  File "/home/wroy/.local/lib/python3.11/site-packages/poxy/run.py", line 493, in postprocess_xml
    sections[header.text].append(section)
             ^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'text'

I don't have much information on what's causing this, but let me know if there's some flags you want me to pass for logs and details

opened by wroyca 3

Feature Request: recursive_paths should find src/ and include/ from the top level directory by default
Poxy currently relies on the recursive_paths option to find the source files. Instead, it should look for src/ and include/ in the top-level directory of the project

# this is a config file for Poxy - a Doxygen + m.css front-end written in Python. # https://github.com/marzer/poxy name = 'foo' github = 'foo/foo' [sources] - recursive_paths = [ '../src' ] extract_all = true
opened by wroyca 3
Add ixx module extension in source patterns

As things get better with C++ modules, it may now be useful to add support for the ixx module extension. Unlike a typical translation unit, there is no header separation for writing the documentation. This means that we must either A: write the documentation inline in the module, or B: write the documentation off-source in .dox files. Whichever choice we make, the module extension, just like the headers previously used, must be parsed by doxygen.

opened by wroyca 1
draft: m.css light theme

This is a draft PR for everything related to improving the light theme. Note that this PR is extremely volatile.

Signed-off-by: William Roy [email protected]

opened by wroyca 1

Poxy looks for Libxml2 which is not installed by default on Windows

"C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.35.32019\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD -I/usr/include/libxml2 "-IC:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.35.32019\include" "-IC:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.35.32019\ATLMFC\include" "-IC:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Auxiliary\VS\include" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.22000.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22000.0\\um" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22000.0\\shared" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22000.0\\winrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22000.0\\cppwinrt" /TcC:\Users\wroy\AppData\Local\Temp\xmlXPathInitxjkf60b1.c /FoUsers\wroy\AppData\Local\Temp\xmlXPathInitxjkf60b1.obj
      xmlXPathInitxjkf60b1.c
      C:\Users\wroy\AppData\Local\Temp\xmlXPathInitxjkf60b1.c(1): fatal error C1083: Cannot open include file: 'libxml/xpath.h': No such file or directory
      error: command 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Preview\\VC\\Tools\\MSVC\\14.35.32019\\bin\\HostX86\\x64\\cl.exe' failed with exit code 2
      *********************************************************************************
      Could not find function xmlCheckVersion in library libxml2. Is libxml2 installed?
      *********************************************************************************
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.

Can be fixed by installing lxml-4.9.0-cp311-cp311-win_amd64.whl from https://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml

bug

opened by wroyca 7

Poxy (more specifically, m.css) crashes when there are many XML files

Poxy will crash if we stress it with a large project. Can be reproduced with, for example, https://github.com/GNOME/gtkmm (note that you have to build it first to generate the .cc .h files)

cc @mosra

Post-processing 1656 XML files
Generating HTML files with m.css
m.css failed!

    Traceback (most recent call last):
      File "/home/wroy/.local/lib/python3.11/site-packages/poxy/data/m.css/documentation/doxygen.py", line 4008, in <module>
        run(state, templates=os.path.abspath(args.templates), wildcard=args.wildcard, index_pages=args.index_pages, search_merge_subtrees=not args.search_no_subtree_merging, search_add_lookahead_barriers=not args.search_no_lookahead_barriers, search_merge_prefixes=not args.search_no_prefix_merging)
      File "/home/wroy/.local/lib/python3.11/site-packages/poxy/data/m.css/documentation/doxygen.py", line 3865, in run
        parsed = parse_xml(state, file)
                 ^^^^^^^^^^^^^^^^^^^^^^
      File "/home/wroy/.local/lib/python3.11/site-packages/poxy/data/m.css/documentation/doxygen.py", line 3132, in parse_xml
        func = parse_func(state, memberdef)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/wroy/.local/lib/python3.11/site-packages/poxy/data/m.css/documentation/doxygen.py", line 2058, in parse_func
        if signature.endswith('=default'):
           ^^^^^^^^^^^^^^^^^^
    AttributeError: 'NoneType' object has no attribute 'endswith'

Traceback (most recent call last):
  File "/home/wroy/.local/lib/python3.11/site-packages/poxy/main.py", line 160, in main
    run(
  File "/home/wroy/.local/lib/python3.11/site-packages/poxy/run.py", line 1269, in run
    run_python_script(
  File "/home/wroy/.local/lib/python3.11/site-packages/misk/functions.py", line 331, in run_python_script
    return subprocess.run(
           ^^^^^^^^^^^^^^^
  File "/usr/lib64/python3.11/subprocess.py", line 569, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['python3', '/home/wroy/.local/lib/python3.11/site-packages/poxy/data/m.css/documentation/doxygen.py', '/tmp/poxy/home_wroy_Projects_mm_docs/conf.py', '--no-doxygen', '--sort-globbed-files']' returned non-zero exit status 1.

bug m.css

opened by wroyca 8

Releases(v0.12.1)

v0.12.1(Nov 22, 2022)
fixed github and gitlab config options not accepting periods (.)

Source code(tar.gz)
Source code(zip)
v0.12.0(Nov 13, 2022)
fixed AttributeError during XML post-processing (#17) (@wroyca)

added command-line option --bug-report

improved diagnostic text in some areas

Source code(tar.gz)
Source code(zip)
v0.11.1(Oct 23, 2022)
fixed crash when using <a> tags in navbar

Source code(tar.gz)
Source code(zip)
v0.11.0(Oct 21, 2022)
added syntax highlighting for functions

improved syntax highlighting of typenames

Source code(tar.gz)
Source code(zip)
v0.10.2(Oct 16, 2022)
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

Source code(tar.gz)
Source code(zip)
v0.10.1(Oct 15, 2022)
minor style fixes

Source code(tar.gz)
Source code(zip)
v0.10.0(Oct 14, 2022)
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

Source code(tar.gz)
Source code(zip)
v0.9.1(Oct 4, 2022)
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

Source code(tar.gz)
Source code(zip)
v0.9.0(Oct 3, 2022)
added support for C++20 concepts 🎉

Source code(tar.gz)
Source code(zip)
v0.8.2(Oct 1, 2022)
added post-process to inline all local SVGs

minor style fixes

Source code(tar.gz)
Source code(zip)
v0.8.1(Sep 30, 2022)
minor style fixes

Source code(tar.gz)
Source code(zip)
v0.8.0(Sep 29, 2022)
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

Source code(tar.gz)
Source code(zip)
v0.7.1(Sep 8, 2022)
fixed crash on python <= 3.8 (#9) (@wroyca)

Source code(tar.gz)
Source code(zip)
v0.7.0(Sep 7, 2022)
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

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

Source code(tar.gz)
Source code(zip)
v0.6.1(Aug 16, 2022)
Fixed multi-row navbar occluding page content (#3) (@wroyca)

Source code(tar.gz)
Source code(zip)
v0.6.0(Aug 14, 2022)
Fixed malformed error messages in some circumstances

Added builtin C++ standard macros for C++23

Added changelog config option

Updated cppreference.com tagfile

Source code(tar.gz)
Source code(zip)
v0.5.7(May 17, 2022)
Fixed being able to pass >= 33 threads to Doxygen's NUM_PROC_THREADS

Source code(tar.gz)
Source code(zip)
v0.5.6(May 14, 2022)
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

Source code(tar.gz)
Source code(zip)
v0.5.5(Apr 16, 2022)
Fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)

Source code(tar.gz)
Source code(zip)
v0.5.4(Apr 15, 2022)
Updated m.css

Updated emoji database

Source code(tar.gz)
Source code(zip)
v0.5.3(Dec 12, 2021)
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

Source code(tar.gz)
Source code(zip)
v0.5.2(Nov 2, 2021)
Fixed over-eager link-replacement for internal #anchor links

Added command-line options --ppinclude and --ppexclude

Source code(tar.gz)
Source code(zip)
v0.5.1(Oct 9, 2021)
Fixed over-eager link replacement causing text to be deleted

Source code(tar.gz)
Source code(zip)
v0.5.0(Sep 11, 2021)
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

Source code(tar.gz)
Source code(zip)
v0.4.5(Jun 8, 2021)
Added command-line option --xmlonly

Source code(tar.gz)
Source code(zip)
v0.4.3(May 31, 2021)
Fixed regression in [code_blocks] functionality

Fixed minor issues in syntax highlighter

Added symbols from doxygen tagfiles to the syntax highlighter

Minor style tweaks

Source code(tar.gz)
Source code(zip)
v0.4.1(May 30, 2021)
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

Source code(tar.gz)
Source code(zip)
v0.4.0(May 29, 2021)
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

Source code(tar.gz)
Source code(zip)
v0.3.4(May 28, 2021)
Added basic using alias detection to syntax highlighter

Added missing badges for C++23, 26 and 29

Source code(tar.gz)
Source code(zip)
v0.3.3(May 23, 2021)
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

Source code(tar.gz)
Source code(zip)

Owner

Mark Gillard

Australian in Finland. I write code. Some of it is alright.

GitHub

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Introduction Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without

23.2k Dec 29, 2022

A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

831 Dec 27, 2022

Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

808 Dec 27, 2022

Swagger Documentation Generator for Django REST Framework: deprecated

Django REST Swagger: deprecated (2019-06-04) This project is no longer being maintained. Please consider drf-yasg as an alternative/successor. I haven

2.6k Jan 3, 2023

Markdown documentation generator from Google docstrings

mkgendocs A Python package for automatically generating documentation pages in markdown for Python source files by parsing Google style docstring. The