[
{
"path": ".github/FUNDING.yml",
"content": "# These are supported funding model platforms\n\ngithub: breathe-doc\npatreon: # Replace with a single Patreon username\nopen_collective: breathe\nko_fi: # Replace with a single Ko-fi username\ntidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\ncommunity_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\nliberapay: # Replace with a single Liberapay username\nissuehunt: # Replace with a single IssueHunt username\notechie: # Replace with a single Otechie username\nlfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry\ncustom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']\n"
},
{
"path": ".github/dependabot.yml",
"content": "version: 2\nupdates:\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"monthly\"\n groups:\n github-actions:\n patterns:\n - \"*\"\n"
},
{
"path": ".github/workflows/cache_doxygen.yml",
"content": "name: download and cache Doxygen\non:\n workflow_call\njobs:\n install:\n runs-on: ubuntu-latest\n concurrency:\n group: linux-doxygen-${{ matrix.doxygen-version }}-cache\n strategy:\n fail-fast: false\n matrix:\n doxygen-version: ['1.9.4', '1.9.7']\n steps:\n - uses: actions/cache/restore@v4\n id: cache-doxygen\n with:\n path: doxygen-bin-arc\n key: ${{ runner.os }}-doxygen-${{ matrix.doxygen-version }}\n lookup-only: true\n restore-keys: |\n ${{ runner.os }}-doxygen-\n\n # TODO: Change to using github release downloads if possible\n - name: download Doxygen from SF binary archives\n if: steps.cache-doxygen.outputs.cache-hit != 'true'\n run: |\n mkdir doxygen-bin-arc && cd doxygen-bin-arc\n curl -L https://sourceforge.net/projects/doxygen/files/rel-${{ matrix.doxygen-version }}/doxygen-${{ matrix.doxygen-version }}.linux.bin.tar.gz > doxygen.tar.gz\n\n - uses: actions/cache/save@v4\n if: steps.cache-doxygen.outputs.cache-hit != 'true'\n with:\n path: doxygen-bin-arc\n key: ${{ steps.cache-doxygen.outputs.cache-primary-key }}\n"
},
{
"path": ".github/workflows/create-release.yml",
"content": "name: Create release\n\non:\n push:\n tags:\n - \"v*\"\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\nenv:\n FORCE_COLOR: \"1\"\n UV_SYSTEM_PYTHON: \"1\" # make uv do global installs\n\njobs:\n publish-pypi:\n runs-on: ubuntu-latest\n name: PyPI Release\n environment: release\n if: github.repository_owner == 'breathe-doc'\n permissions:\n id-token: write # for PyPI trusted publishing\n steps:\n - uses: actions/checkout@v6\n with:\n persist-credentials: false\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: latest\n enable-cache: false\n\n - name: Install Ruff\n uses: astral-sh/ruff-action@v3\n with:\n args: --version\n version: 0.9.2\n\n - name: Install build dependencies (pypa/build, twine)\n # Install jinja2 to make the parser - probably better to install it via\n # the Sphinx dependency in the pyproject.toml file but I don't know how\n # to do that at the moment\n run: uv pip install build \"twine>=5.1\" \"jinja2>=3.1.6\" setuptools\n\n - name: Generate parser\n run: |\n make parser\n make format-parser\n\n - name: Build distribution\n run: python -m build\n\n - name: Check distribution\n run: |\n twine check --strict dist/*\n\n - name: Upload to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n"
},
{
"path": ".github/workflows/documentation.yml",
"content": "name: Build documentation\n\non:\n pull_request:\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\nenv:\n DOXYGEN_VERSION: 1.9.4\n FORCE_COLOR: \"1\"\n\njobs:\n cache-doxygen:\n uses: ./.github/workflows/cache_doxygen.yml\n\n build:\n needs: cache-doxygen\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3\"\n cache: 'pip'\n\n - name: Install apt dependencies\n run: |\n sudo apt-get -y update\n sudo apt-get -y install graphviz\n\n - uses: actions/cache/restore@v4\n id: cache-doxygen\n with:\n path: doxygen-bin-arc\n fail-on-cache-miss: true\n key: ${{ runner.os }}-doxygen-${{ env.DOXYGEN_VERSION }}\n\n - name: Install doxygen\n # at some point actions/cache/restore@4 started unpacking doxygen.tar.gz\n # automatically and I don't know why -- Rouslan\n run: |\n cd doxygen-bin-arc\n if test -d doxygen; then\n cd doxygen\n else\n gunzip doxygen.tar.gz\n tar xf doxygen.tar\n cd doxygen-${{ env.DOXYGEN_VERSION }}\n fi\n sudo make install\n\n - name: Install Python dependencies\n run: |\n python -m pip install --upgrade pip\n python -m pip install --editable .[build]\n python -m pip install .[docs]\n # Remove the version of breathe that is automatically installed by the previous commands\n # as it confuses the build. This build should pick up breathe from the repo source\n python -m pip uninstall --yes breathe\n\n - name: Build the documentation\n run: |\n make parser\n make html\n rm documentation/build/html/.buildinfo\n\n - uses: actions/upload-artifact@v5\n with:\n name: docs build artifacts\n path: |\n documentation/build/html\n examples/*/*/xml\n"
},
{
"path": ".github/workflows/lint.yml",
"content": "name: Lint source code\n\non:\n pull_request:\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\nenv:\n FORCE_COLOR: \"1\"\n\njobs:\n ruff:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n with:\n persist-credentials: false\n\n - name: Install Ruff\n uses: astral-sh/ruff-action@v3\n with:\n args: --version\n version: 0.9.2\n\n - name: Install dependencies\n # \"--editable\" is needed so that _parser.py is placed in the local folder\n # where pytest will import from\n run: |\n python -m pip install --upgrade pip\n python -m pip install --editable \".[build]\"\n\n - name: Generate parser\n run: |\n make parser\n make format-parser\n\n - name: Lint with Ruff\n run: ruff check --output-format=github\n\n - name: Format with Ruff\n run: ruff format --diff\n\n mypy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3\"\n\n - name: Install dependencies\n # \"--editable\" is needed so that _parser.py is placed in the local folder\n # where pytest will import from\n run: |\n python -m pip install --upgrade pip\n python -m pip install --editable \".[build]\"\n python -m pip install --editable \".[lint]\"\n\n - name: Generate parser\n run: make parser\n\n - name: Type check with mypy\n run: mypy --warn-redundant-casts --warn-unused-ignores breathe tests\n\n twine:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3\"\n\n - name: Install dependencies\n # \"--editable\" is needed so that _parser.py is placed in the local folder\n # where pytest will import from\n run: |\n python -m pip install --upgrade pip\n python -m pip install --upgrade twine build\n python -m pip install --editable \".[build]\"\n\n - name: Generate parser\n run: make parser\n\n - name: Lint with twine\n run: |\n python -m build .\n twine check dist/*\n"
},
{
"path": ".github/workflows/unit_tests.yml",
"content": "name: Tests\n\non:\n pull_request:\n paths:\n - \".github/workflows/unit_tests.yml\"\n - \"breathe/**\"\n - \"tests/**\"\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\nenv:\n FORCE_COLOR: \"1\"\n PYTHONDEVMODE: \"1\" # -X dev\n PYTHONWARNDEFAULTENCODING: \"1\" # -X warn_default_encoding\n\njobs:\n cache-doxygen:\n uses: ./.github/workflows/cache_doxygen.yml\n\n test:\n needs: cache-doxygen\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n doxygen-version:\n - '1.9.4'\n - '1.9.7'\n python-version:\n - '3.9'\n - '3.10'\n - '3.11'\n - '3.12'\n - '3.13'\n sphinx-version:\n - '6.2'\n - '7.0'\n - '7.1'\n - '7.2' # Ubuntu 24.04\n # version 7.3 broke up the domain modules into packages, changing\n # where some classes had to be imported from\n - '7.3'\n - '7.4' # Ubuntu 24.10\n - '8.0'\n - '8.1' # Ubuntu 25.04\n - '8.2' # Ubuntu 25.04\n exclude:\n - python-version: '3.9'\n sphinx-version: '8.0'\n - python-version: '3.9'\n sphinx-version: '8.1'\n - python-version: '3.9'\n sphinx-version: '8.2'\n - python-version: '3.9'\n sphinx-version: 'latest'\n\n - python-version: '3.10'\n sphinx-version: '8.2'\n - python-version: '3.10'\n sphinx-version: 'latest'\n\n steps:\n - uses: actions/checkout@v6\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v6\n with:\n python-version: ${{ matrix.python-version }}\n cache: 'pip'\n\n - name: Install Sphinx ${{ matrix.sphinx-version }}\n if: matrix.sphinx-version != 'latest'\n run: |\n python -m pip install -Iv Sphinx==${{ matrix.sphinx-version }}\n \n - name: Install Sphinx master\n if: matrix.sphinx-version == 'latest'\n run: |\n python -m pip install \"Sphinx @ git+https://github.com/sphinx-doc/sphinx.git@master\"\n\n - uses: actions/cache/restore@v4\n id: cache-doxygen\n with:\n path: doxygen-bin-arc\n fail-on-cache-miss: true\n key: ${{ runner.os }}-doxygen-${{ matrix.doxygen-version }}\n\n - name: Install doxygen\n # at some point actions/cache/restore@4 started unpacking doxygen.tar.gz\n # automatically and I don't know why -- Rouslan\n run: |\n cd doxygen-bin-arc\n if test -d doxygen; then\n cd doxygen\n else\n gunzip doxygen.tar.gz\n tar xf doxygen.tar\n cd doxygen-${{ matrix.doxygen-version }}\n fi\n sudo make install\n\n - name: Install dependencies\n # \"--editable\" is needed so that _parser.py is placed in the local\n # folder where pytest will import from\n run: |\n pip install --upgrade pip\n pip install --editable .[build]\n pip install --editable .[test]\n\n - name: Generate parser\n run: |\n make parser\n\n - name: Test with pytest\n if: matrix.sphinx-version != 'latest'\n run: python -m pytest -vv\n env:\n PYTHONWARNINGS: \"error\" # treat all warnings as errors\n \n - name: Test with pytest\n if: matrix.sphinx-version == 'latest'\n run: python -m pytest -vv\n"
},
{
"path": ".gitignore",
"content": "*.pyc\n/.project\n/.pydevproject\nbuild/\n/dist\n/breathe.egg-info\n/.mypy_cache\n\n# Folder for placing stuff to be ignored\n/ignored\n\n# My virtual env folder\n/python-2.7.4\n\n# Test folder for building simple examples of the documentation\n/simple\n\n# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm\n\n## Directory-based project format\n.idea/\n# if you remove the above rule, at least ignore user-specific stuff:\n# .idea/workspace.xml\n# .idea/tasks.xml\n# and these sensitive or high-churn files:\n# .idea/dataSources.ids\n# .idea/dataSources.xml\n# .idea/sqlDataSources.xml\n# .idea/dynamic.xml\n\n## File-based project format\n*.ipr\n*.iws\n*.iml\n\n## Additional for IntelliJ\nout/\n\n# generated by mpeltonen/sbt-idea plugin\n.idea_modules/\n\n# generated by JIRA plugin\natlassian-ide-plugin.xml\n\n# generated by Crashlytics plugin (for Android Studio and Intellij)\ncom_crashlytics_export_strings.xml\n\n# modified by build process\nexamples/doxygen/example.tag\nexamples/specific/dot_graphs/xml/dotfile.dot\n\n# generated in editable install\n/breathe/_parser.py\n"
},
{
"path": ".readthedocs.yaml",
"content": "version: 2\n\npython:\n version: 3\n\nsphinx:\n builder: html\n configuration: documentation/source/conf.py\n fail_on_warning: false\n\nconda:\n environment: documentation/environment.yaml\n"
},
{
"path": ".ruff.toml",
"content": "target-version = \"py39\" # Pin Ruff to Python 3.9\nline-length = 100\noutput-format = \"full\"\n\n[format]\npreview = true\nquote-style = \"double\"\n\n[lint]\npreview = true\nignore = [\n \"UP031\", # Use format specifiers instead of percent format\n]\nselect = [\n \"C4\", # flake8-comprehensions\n# \"B\", # flake8-bugbear\n# \"D\", # pydocstyle\n \"E\", # pycodestyle\n \"F\", # pyflakes\n \"FA\", # flake8-future-annotations\n \"FLY\", # flynt\n \"FURB\", # refurb\n \"G\", # flake8-logging-format\n \"I\", # isort\n \"LOG\", # flake8-logging\n# \"N\", # pep8-naming\n \"PERF\", # perflint\n \"PGH\", # pygrep-hooks\n \"PT\", # flake8-pytest-style\n \"TC\", # flake8-type-checking\n \"TID\", # flake8-tidy-imports\n \"UP\", # pyupgrade\n \"W\", # pycodestyle\n]\n\n[lint.per-file-ignores]\n\"breathe/parser/{compound,index}super.py\" = [\n \"E266\", # Too many leading `#` before block comment\n]\n\n\"examples/doxygen/pyexample.py\" = [\n \"E266\", # Too many leading `#` before block comment\n]\n\n[lint.flake8-quotes]\ninline-quotes = \"double\"\n\n[lint.flake8-type-checking]\nexempt-modules = []\nstrict = true\n\n[lint.flake8-tidy-imports]\nban-relative-imports = \"all\"\n\n[lint.isort]\nforced-separate = [\n \"tests\",\n]\nrequired-imports = [\n \"from __future__ import annotations\",\n]\n\n[lint.pydocstyle]\nconvention = \"pep257\"\nignore-decorators = [\"typing.overload\"]\nignore-var-parameters = true\n"
},
{
"path": "CHANGELOG.rst",
"content": "Change Log\n----------\n\nInspired by `Keepachangelog.com `__.\n\n- 2025-07-08 - **Breathe v5.0.0a5**\n\n Adjust create-release process to include ruff for formatting generated ``_parser.py`` file.\n\n- 2025-07-08 - **Breathe v5.0.0a4**\n\n Adjust create-release process to try to generate ``_parser.py`` file.\n\n- 2025-07-08 - **Breathe v5.0.0a3**\n\n Adjust create-release process to try to generate ``_parser.py`` file.\n\n- 2025-07-08 - **Breathe v5.0.0a2**\n\n - Removed sphinx_csharp git-based dependency\n `#1035 `__\n\n- 2025-07-08 - **Breathe v5.0.0a1**\n\n Alpha release of v5. Contains a significant refactor of the internal logic.\n\n Thanks to @JasperCraeghs and @Rouslan.\n\n - Merging long standing refactor branches\n `#1029 `__\n - Performance improvements, new tests, more typing annotations and miscellaneous fixes\n `#967 `__\n - Support members in a Doxygen 1.9.7 group\n `#934 `__\n - Fix docstring missing quotes\n `#1020 `__\n - Fix docstring missing quotes\n `#1020 `__\n - Fix some incorrect indents in the document\n `#1032 `__\n - Enable imgconverter extension to fix LaTeX documentation build\n `#1027 `__\n - Bump astral-sh/setup-uv from 5 to 6 in the github-actions group\n `#1025 `__\n\n- 2025-02-22 - **Breathe v4.36.0**\n\n - Update `test_renderer` so that tests pass with Sphinx 7.2.\n `#976 `__\n - Fix PosixPath issue with Sphinx 7.2.\n `#964 `__\n - Avoid `RemovedInSphinx80Warning` in path-manipulation code.\n `#977 `__\n - Require Sphinx 7.2 or later, Python 3.9 or later,\n and Doxygen 1.9.2 or later.\n `#887 `__,\n `#946 `__\n `#955 `__\n - Begin to use pathlib.\n - Resolve full title for doxygenpage and doxygengroup\n and allow for omitting the title all together\n `#939 `__\n - Insert signature name for use with Sphinx Table of Contents\n `#959 `__\n - Fix test failure with latest Sphinx master.\n `#1010 `__\n - Fix error in template specialization with qualified arguments\n `#1010 `__\n\n- 2023-02-28 - **Breathe v4.35.0**\n\n - Pull lone literal blocks in paragraphs up to produce correct doctree.\n `#833 `__\n - Fix tests for changes in Sphinx 5.3.\n `#865 `__\n - Bump Python requirement to 3.7.\n `#866 `__\n - Support Sphinx 6.\n `#885 `__\n - Support ``:sort:`` option to sort sections by name.\n `#879 `__\n\n- 2022-06-20 - **Breathe v4.34.0**\n\n - Treat .unparsed as plain text.\n `#806 `__\n - Remove unneeded type: ignore annotations.\n `#813 `__\n - Fix internal ``NodeFinder`` visitor for when non-Docutils nodes are\n present in the content of a directive.\n `#812 `__\n - Rename lint workflow.\n `#814 `__\n - Type check pygments and limit docutils stub version.\n `#819 `__\n - Convert dot files' relative path to absolute.\n `#821 `__\n - CI, update Sphinx versions to test.\n `#834 `__\n - CI, update for Sphinx 5.0.1.\n `#846 `__\n - Fix inconsistency in example.\n `#843 `__\n - Fix C# enum rendering crash.\n `#849 `__\n - Drop Sphinx 3 support, add Sphinx 5 support.\n `#850 `__\n - CICD: Disable python 3.6 for Sphinx master tests.\n `#853 `__\n - Populate default include text-node's data field instead of raw-source.\n `#828 `__\n\n- 2022-02-14 - **Breathe v4.33.1**\n\n - Avoid warning about multiple graphviz directives.\n `#804 `__\n\n- 2022-02-14 - **Breathe v4.33.0**\n\n - Fix duplicate ``static`` in variable declarations.\n `#794 `__\n - Update CICD for Sphinx 4.4.0 series.\n `#795 `__\n - Pin version of black in CICD and reformat files.\n `#792 `__\n - Fix code block highlighting.\n `#760 `__\n - Refactoring, cleanup and typing improvements.\n `#802 `__\n - Doxygen dot graphs to Sphinx graphviz.\n `#757 `__\n - Support externally hosted images.\n `#705 `__\n - Address a peculiarity in Doxygen aliases in doc.\n `#770 `__\n - Add flag to doxygengroup, doxygennamespace to display only the description.\n `#718 `__\n - Add support for MD block quotes with attribution(s).\n `#759 `__\n\n- 2022-01-30 - **Breathe v4.32.0**\n\n - Added ``breathe_doxygen_aliases`` config variable.\n `#729 `__\n - Render ``\\remark``/``\\remarks`` and ``\\see``/``\\sa`` using Sphinx/Docutils\n admonition style nodes.\n `#756 `__\n - Render C++ scoped enums differently than unscoped enums, and with their\n underlying type.\n `#753 `__\n - Render ``\\retval`` lists using dedicated field list when Sphinx >= 4.3 is\n used.\n `#749 `__\n - Make ``.. doxygenfunction`` handle function template specializations.\n `#750 `__\n - Properly handle field-lists and admonitions in the detailed description of\n classes and functions.\n `#764 `__\n - Add ``:confval:`breathe_show_include``` to control whether ``#include``\n lines are shown. Defaults to ``True``.\n `#725 `__\n - Fix sys.path adjustment in doc config.\n `#734 `__\n - Fix sphinx renderer variable and function visitors for C#.\n `#737 `__\n - Fix sphinx renderer class visitor for C#.\n `#738 `__\n - Auto-format python code with black.\n `#743 `__\n - Extend flake8 and address some style issues.\n `#745 `__\n - Fix black formatting warning.\n `#747 `__\n - Update Sphinx and Python versions tested against.\n `#765 `__\n - Fix friend functions for older Doxygen versions.\n `#769 `__\n - Doxygen >= 1.9.2 supports C++20 concepts, add support for them.\n `#779 `__\n - Change the way directives are added to adhere to the interface,\n e.g., avoiding myst-parser to crash.\n `#780 `__\n - Improved list of included files (with cross-references for local includes).\n `#763 `__\n - Update flake8 and mypy related stuff.\n `#781 `__\n - Update readme with logo and sponsorship info.\n `#784 `__\n - Store version number in both setup.py and __init__.py.\n `#789 `__\n - CICD: lint: continue with other jobs if black fails.\n `#791 `__\n\n- 2021-09-14 - **Breathe v4.31.0**\n\n - Collapse multiple retvals into a single bullet list. `#697 `__\n - Fix mypy issues on CI. `#731 `__\n - Print usage message from 'compare' doc script. `#727 `__\n - Test against Sphinx 4.0.3, 4.1.2 and 4.1.x branch. `#721 `__\n - Fix duplicate ``static`` in function declarations. `#717 `__ `#720 `__\n - Directive refactoring. `#698 `__\n - Handle parsing errors. `#711 `__\n - Make doxygenfunction more robust when matching parameters. `#722 `__ `#723 `__\n - Separate, link and style the changelog. `#735 `__\n - Update changelog and readme ahead of release. `#739 `__\n - CICD: Track Sphinx 4.2.x development series. `#741 `__\n\n- 2021-05-06 - **Breathe v4.30.0**\n\n - Fix retval rendering. `#687 `__\n - Correctly label example as C. `#690 `__\n - apidoc: add -m, --members option flag. `#694 `__\n\n- 2021-04-30 - **Breathe v4.29.2**\n\n - Remove stale six dep. `#682 `__\n - Render fields with multiple names instead of crashing. `#685 `__\n - Start pytest via module instead of exe. `#686 `__\n\n- 2021-04-23 - **Breathe v4.29.1**\n\n - Splice out parameter direction in field lists. `#675 `__\n - Fixes for Sphinx v4. `#676 `__\n - Fix paragraph in paragraph rendering. `#678 `__\n - Strip names before lookup in doxygenfunction. `#679 `__\n - When rendering template params, insert name by parsing. `#681 `__\n\n- 2021-04-09 - **Breathe v4.29.0**\n\n - Do not add inline modifier for C#. `#668 `__\n - Use add_css_file instead of deprecated/removed add_stylesheet. `#669 `__\n - Use native docutils for field lists, notes, and warnings. `#670 `__\n - Handle directives returning no nodes on error. `#672 `__\n\n- 2021-03-29 - **Breathe v4.28.0**\n\n - Code and documentation for membergroups and members-only options. `#637 `__\n - Add example.tag to gitignore as it gets modified during build process. `#644 `__\n - Add support for content-only flag when rendering pages. `#645 `__\n - When rendering a section, add target after title. `#647 `__\n - Render pages content in order. `#651 `__\n - Adds an ID to the rubric created for each section of a group. `#658 `__\n - Add missing getter and setter for C#. `#661 `__\n - Add support for rowspan/colspan to tables. `#642 `__\n\n- 2021-02-16 - **Breathe v4.27.0**\n\n - Add various specifiers to functions and variables. `#628 `__\n - Add multiply inherited class for PHP objects. `#630 `__\n - Initial support for table rendering. `#632 `__\n - Add rendering of \\section, \\subsection and \\subsubsection. `#635 `__\n - Sphinx 3.5 compatibility. `#640 `__\n - Fix linking to sections. `#639 `__\n - Add table examples to documentation. `#638 `__\n\n- 2021-01-21 - **Breathe v4.26.1**\n\n - Fix doxygenfile causing duplicate IDs for unspecified sections. `#622 `__\n - Fixes for doxygenfunction (friend keyword, friend class, arg checks). `#623 `__\n\n- 2021-01-08 - **Breathe v4.26.0**\n\n - Add test for ellipsis ('...') in args. `#610 `__\n - Sphinx 3.4.x compatibility. `#617 `__\n - Adapt friendclass to Doxygen 1.9. `#618 `__\n\n- 2020-12-16 - **Breathe v4.25.1**\n\n - Addendum to #606, for functions with '...'. `#609 `__\n\n- 2020-12-15 - **Breathe v4.25.0**\n\n - Add support for \\parblock parsing and rendering. `#603 `__\n - Allow lookup in doxygenfunction without writing param names. `#606 `__\n\n- 2020-12-01 - **Breathe v4.24.1**\n\n - Fix anchors on pages generated by Doxygen >= 1.8.17. `#602 `__\n\n- 2020-11-15 - **Breathe v4.24.0**\n\n - Update CI for Sphinx 3.3.x and fix test mock. `#597 `__\n - Add support for xrefitem based page generation (doxygenpage). `#596 `__\n\n- 2020-10-20 - **Breathe v4.23.0**\n\n - Add initial xrefsect support. `#589 `__\n\n- 2020-09-26 - **Breathe v4.22.1**\n\n - Fix anonymous struct/union usage in C domain. `#585 `__\n\n- 2020-09-19 - **Breathe v4.22.0**\n\n - Fix Read the Docs build (again). `#576 `__\n - New boolean `breathe_show_enumvalue_initializer` option specifying\n whether value of enumvalue should be displayed. `#581 `__\n\n- 2020-09-10 - **Breathe v4.21.0**\n\n - Fix Read the Docs build. `#567 `__\n - Document doxygenclass template specialisation spacing. `#570 `__\n - Update upper Sphinx release to <3.4. `#571 `__\n - Reuse breathe.__version__ in setup.py. `#572 `__\n - Document :inner: for the doxygengroup section. `#573 `__\n - Add support for verbatim inline elements. `#560 `__\n - Fix wrong refid when Doxygen SEPARATE_MEMBER_PAGES is YES. `#566 `__\n\n- 2020-08-19 - **Breathe v4.20.0**\n\n - Allow Sphinx 3.2. `#561 `__\n - Update CI scripts with new Sphinx versions. `#552 `__\n - Add support for C# using sphinx-csharp. `#550 `__\n - Doc, fix typo, :source: -> :project:. `#551 `__\n - Add support for innergroup. `#556 `__\n - Avoid duplicate doxygen targets when debug tracing. `#563 `__\n - Remove Travis badge from README file. `#564 `__\n\n- 2020-06-17 - **Breathe v4.19.2**\n\n - Fix crash when visiting typedef. `#547 `__\n\n- 2020-06-08 - **Breathe v4.19.1**\n\n - Mark package as compatible with Sphinx 3.1.\n\n- 2020-06-07 - **Breathe v4.19.0**\n\n - Refactoring. `#528 `__\n - Make debug config variables available in conf.py. `#533 `__\n - Fix warning formatting for function lookup. `#535 `__\n - Correctly reverse nested namespaces in get_qualification. `#540 `__\n\n- 2020-05-10 - **Breathe v4.18.1**\n\n - Fix friend class rendering and allow friend struct. `#522 `__\n - Add extern examples to doc and remove variable hack. `#526 `__\n - Render function candidates without using Sphinx directives. `#524 `__\n\n- 2020-05-02 - **Breathe v4.18.0**\n\n - Support tiles in verbatim blocks. `#517 `__\n\n- 2020-05-01 - **Breathe v4.17.0**\n\n - Scoped rendering, better integration with Sphinx, misc fixes. `#512 `__\n\n- 2020-04-19 - **Breathe v4.16.0**\n\n - Strictly depend on Sphinx's minor version. `#498 `__\n - Simplifications and fixes, use more of modern Sphinx natively. `#503 `__\n - Add section option to the doxygen(auto)file directive. `#501 `__\n - Fix link generation when enum is inside a group (enum FQDN). `#508 `__\n - Fix creation of LaTeX math formulas. `#506 `__\n - Improve documentation for doxygen(auto)file section option. `#509 `__\n\n- 2020-04-07 - **Breathe v4.15.0**\n\n - Add license file to distribution. `#492 `__\n - Update for Sphinx 3. `#491 `__\n\n- 2020-04-07 - **Breathe v4.14.2**\n\n - Add GitHub actions. `#474 `__\n - Fixes to use Sphinx 2.4.4. `#486 `__\n - Add nose to python development requirements. #484.\n - Switch to pytest from nose. `#487 `__\n\n- 2020-02-02 - **Breathe v4.14.1**\n\n - Use sphinx core instead of mathbase ext. `#469 `__\n - Fix test failure for Sphinx >= 2.2.2. `#472 `__\n - Update travis to Sphinx 2.3.1. `#471 `__\n\n- 2019-11-26 - **Breathe v4.14.0**\n\n - Add events attribute to MockApp. `#452 `__\n - Add bit field support for C/C++. `#454 `__\n - Add alias and variable template support. `#461 `__\n\n- 2019-08-01 - **Breathe v4.13.1**\n\n - Fix for template method pointer parameter issue. `#449 `__\n\n- 2019-04-23 - **Breathe v4.13.0**.post0\n\n - Drop support for python 2, require Sphinx >= 2.0. `#432 `__\n\n- 2019-04-21 - **Breathe v4.13.0**\n\n - Adapt to upcoming Sphinx 2.0. `#411 `__\n - Add support for rendering parameter direction information. `#428 `__\n\n- 2019-03-15 - **Breathe v4.12.0**\n\n - Adapt to Sphinx 1.8. `#410 `__\n - Let Sphinx handle more things. `#412 `__\n - Use standard windows EOL for batch file. `#417 `__\n - Fix flake8 F632 warnings. `#418 `__\n - Update dep versions in readme, setup, requirements. `#419 `__\n - Add option to render function parameters after the description. `#421 `__\n - Remove spurious \"typedef\" in type declaration when using \"using\". `#424 `__\n\n- 2018-12-11 - **Breathe v4.11.1**\n\n - Sphinxrenderer: handle typeless parameters gracefully. `#404 `__\n\n- 2018-10-31 - **Breathe v4.11.0**\n\n - Fix typo in quickstart. `#393 `__\n - Add support for QtSignals. `#401 `__\n\n- 2018-08-07 - **Breathe v4.10.0**\n\n - Explicitly use Sphinx 1.7.5 for CI and dev. `#385 `__\n - Print filename when printing ParserException. `#390 `__\n\n- 2018-06-03 - **Breathe v4.9.1**\n\n - Don't append separator for paragraph type. `#382 `__\n\n- 2018-06-01 - **Breathe v4.9.0**\n\n - Render newlines as separate paragraphs. `#380 `__\n\n- 2018-05-26 - **Breathe v4.8.0**\n\n - Add quiet option to apidoc. `#375 `__\n - Add PHP domain. `#351 `__\n - Keep templates on adjacent lines. `#300 `__\n - Show reference qualification for methods. `#332 `__\n - Adapt tests/CI to newest Sphinx version. `#377 `__\n - More robust name regex in renderer. `#370 `__\n - Show base classes using Sphinx's cpp domain. `#295 `__\n - Fix domain detection when rendering groups. `#365 `__\n - Return parallel_{read,write}_safe true for Sphinx's -j. `#376 `__\n\n- 2017-10-09 - **Breathe v4.7.3**\n\n - Support for enums in the cpp domain.\n - Handle case where compoundref does not have a refid value associated.\n\n- 2017-08-15 - **Breathe v4.7.2**\n\n - Fix issue with packaging on Python 2.7 with wheels.\n\n- 2017-08-13 - **Breathe v4.7.1**\n\n - Fixed bug regarding code snippets inside Doxygen comments.\n\n- 2017-08-09 - **Breathe v4.7.0**\n\n - New `outtypes` option to prevent documenting namespace and files\n\n - New boolean `breathe_show_define_initializer` option specifying whether\n value of macros should be displayed.\n\n - New boolean `breathe_use_project_refids` option controlling whether the\n refids generated by breathe for doxygen elements contain the project name\n or not.\n\n - Fixed\n\n - Support for Sphinx 1.6\n\n- 2017-02-25 - **Breathe v4.6.0**\n\n - Support for the Interface directive\n\n - Display the contents of defines\n\n- 2017-02-12 - **Breathe v4.5.0**\n\n - Improve handling of c typedefs\n\n - Support new `desc_signature_line` node\n\n - Add `--project` flag to breathe-apidoc helper\n\n - Dropped testing for Python 3.3 and added 3.6\n\n- 2016-11-13 - **Breathe v4.4.0**\n\n - Improve single line parameter documentation rendering\n\n- 2016-11-05 - **Breathe v4.3.1**\n\n - Version bump package confusion with wheel release\n\n- 2016-11-05 - **Breathe v4.3.0**\n\n - Rewritten rendering approach to use the visitor pattern\n\n - Dropped support for 2.6 & added testing for 3.5\n\n - Fixed\n\n - Issue with running breathe-apidoc for the first time.\n\n - Improved handling of qualifiers, eg. const & volatile.\n\n - Supports functions in structs\n\n - Supports auto-doxygen code path on Windows\n\n- 2016-03-19 - **Breathe v4.2.0**\n\n - Added\n\n - Output links to a class' parents & children.\n\n - Support for Sphinx's `needs_extensions` config option.\n\n - breathe-apidoc script for generating ReStructuredText stub files with\n Breathe directives from doxygen xml files.\n\n - Fixed\n\n - Handling default values in parameter declarations\n\n - Output order not being reproducible due to iteration over Set.\n\n - Handling of multiple pointers and references\n\n - `SEVERE: Duplicate ID` warnings when using function overloads.\n\n - Use project name for link references when using default project. So we use\n the project name instead of 'project0'.\n\n- 2015-08-27 - **Breathe v4.1.0**\n\n - Added\n\n - ``breathe_doxygen_config_options`` config variable which allows for adding\n more config lines to the doxygen file used for the auto-directives.\n\n - Fixed\n\n - Display of array & array reference parameters for functions.\n\n - Handling of links to classes with template arguments.\n\n - Handling of unnamed enums in C.\n\n - Naming of template parameter section.\n\n - Finding functions that are within groups.\n\n - Rendering of 'typename' and 'class' keywords for templates.\n\n- 2015-04-02 - **Breathe v4.0.0**\n\n - Significant work on the code base with miminal reStructureText interface\n changes. To be documented.\n\n- 2014-11-09 - **Breathe v3.2.0**\n\n - Nothing Added, Deprecated or Removed\n\n - Fixed\n\n - Changed docutils/Sphinx node usage to fix latex/pdf output.\n\n - When checking for path separators check for both ``/`` and ``\\``\n regardless of the platform.\n\n - ``KeyError`` when using ``auto`` directives without specifying the\n ``:project:`` option even though the default project config setting was\n set.\n\n - Use of ``doxygenfunction`` no longer inappropriately triggers the\n duplicate target check and fails to output link targets.\n\n - Support for inline urls in the doxygen comments.\n\n - Support for array notation in function parameters.\n\n - Reduced intention by changing ``section-defs`` to use ``container`` &\n ``rubric`` nodes rather than ``desc`` nodes with signatures & content. Now\n headings like 'Public Functions' appear inline with their subject matter.\n\n- 2014-09-07 - **Breathe v3.1.0**\n\n - Nothing Deprecated or Removed\n\n - Added\n\n - The ``doxygenclass`` directive can now reference template specialisations\n by specifying the specialisation in the argument name.\n\n - Fixed\n\n - Displaying function parameters for Qt slots output. Previously they were\n missing even though Qt Slots are essentially just functions.\n\n - Displaying headings from doxygen comments as emphasized text.\n\n - Crash when generating warning about being unable to find a define,\n variable, enum, typedef or union.\n\n - Only output the definition name for a function parameter if the declartion\n name is not available. Previously, where they were both available we were\n getting two names next to each other for no good reason.\n\n- 2014-08-04 - **Breathe v3.0.0**\n\n - Improve output of const, volatile, virtual and pure-virtual keywords.\n\n - Fix css class output for HTML so that object types rather than names are\n output as the css classes. eg. 'function' instead of 'myFunction'.\n\n - Fix issue with Breathe getting confused over functions appearing in header\n and implementation files.\n\n - Improve matching for overloaded functions when using ``doxygenfunction``\n directive. Also, provide a list of potential matches when no match is found.\n\n - Improved ``:members:`` implementation to handle inner classes properly.\n\n - Updated ``doxygenstruct`` to share the ``doxygenclass`` implementation path\n which grants it the options from ``doxygenclass`` directive.\n\n - Added ``:outline:`` option support to ``doxygengroup`` &\n ``doxygennamespace`` directives.\n\n - Added ``doxygennamespace`` directive.\n\n - Added ``:undoc-members:`` option to ``doxygenclass`` & ``doxygengroup``\n directives.\n\n - **Breaking change**: Removed ``:sections:`` option for ``doxygenclass`` &\n ``doxygengroup`` directives and replaced it with ``:members:``,\n ``:protected-members:`` and ``:private-members:``, and changed\n ``breathe_default_sections`` config variable to ``breathe_default_members``.\n This is designed to more closely match the Sphinx autodoc functionality and\n interface.\n\n- 2014-06-15 - **Breathe v2.0.0**\n\n - Add compare script for checking changes to documentation caused by changes\n in the implementation.\n\n - Switched to ``https`` reference for MathJax Javascript.\n\n - **Breaking change**: Change ``autodoxygen*`` directives to require\n explicitly declared source files in the ``conf.py`` rather than attempting\n to detect them from the directive arguments.\n\n - Switch documentation hosting to ReadTheDocs.org.\n\n - **Breaking change**: Switch to assuming all relative paths are relative to\n the directory holding the ``conf.py`` file. Previously, it would assume they\n were relative to the user's current working directory. This breaks projects\n which use separate build & source directories.\n\n - Add ``doxygenunion`` directive.\n\n - Add ``doxygengroup`` directive.\n\n - Add support for lists in the output. They were previously ignored.\n\n - Updated implementation to use the docutils nodes that Sphinx does where\n possible.\n\n- 2014-06-01 - **Breathe v1.2.0**\n\n - Change log not recorded.\n\n"
},
{
"path": "CONTRIBUTING.rst",
"content": "\nContributing\n============\n\nFirstly, thank you for making it this far. We really appreciate anyone who even\nthinks about reporting an issue or helping out with the code or docs. It is kind\nof you to take the time.\n\nPlease Provide an Example\n-------------------------\n\nIf you're having trouble with how the contents of a particular Doxygen comment\nor a particular set of code is being processed then please provide an example of\nthe in question.\n\nIdeally as a pull-request with additions to the `examples/specific` folder but\nfeel free to provide the comment content in your issue instead.\n\nIt really helps to accelerate development if we have examples to work from.\n"
},
{
"path": "CONTRIBUTORS.rst",
"content": "Contributors\n============\n\nMany thanks to everyone that has contributed to the project.\n\n- `Andne `_\n- `arximboldi `_\n- `D4N `_\n- `dean0x7d `_\n- `dg-dboehi `_\n- `eric-wieser `_\n- `fetzerch `_\n- `gmarull `_\n- `hidmic `_\n- `ishitatsuyuki `_\n- `jakobandersen `_\n- `mattip `_\n- `michaeljones `_\n- `nijel `_\n- `olitheolix `_\n- `pczerkas `_\n- `queezythegreat `_\n- `remyleone `_\n- `rhssk `_\n- `rogerbarton `_\n- `ropg `_\n- `rscohn2 `_\n- `rweickelt `_\n- `SylvainCorlay `_\n- `t-b `_\n- `Tiwalun `_\n- `utzig `_\n- `vermeeren `_\n- `vitaut `_\n- `xuhongxu96 `_\n\nAnd many more via issues and suggestions.\n"
},
{
"path": "LICENSE",
"content": "// BSD license, modified to remove the organisation as there isn't one.\n\nCopyright (c) 2009, Michael Jones\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n\t * Redistributions of source code must retain the above copyright notice,\n\t this list of conditions and the following disclaimer.\n\t * Redistributions in binary form must reproduce the above copyright notice,\n\t this list of conditions and the following disclaimer in the documentation\n\t and/or other materials provided with the distribution.\n\t * The names of its contributors may not be used to endorse or promote\n\t products derived from this software without specific prior written\n\t permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON\nANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n"
},
{
"path": "MANIFEST.in",
"content": "recursive-include xml_parser_generator *.py *.in *.json \ninclude requirements/*.txt tests/*.py\ngraft tests/data\nexclude breathe/_parser.py\nglobal-exclude *.py[cod]"
},
{
"path": "Makefile",
"content": "RM \t\t= rm -f\nGENERATED_MOD\t= breathe/_parser.py\n\n.PHONY: all\nall: html pdf\n\n.PHONY: html\nhtml: data\n\t$(MAKE) -C documentation html\n\n.PHONY: pdf\npdf: data\n\t$(MAKE) -C documentation latexpdf\n\t\n.PHONY: data\ndata:\n\t$(MAKE) -C examples/doxygen all\n\t$(MAKE) -C examples/tinyxml all\n\t$(MAKE) -C examples/specific all\n\n$(GENERATED_MOD): \\\n\t\txml_parser_generator/schema.json \\\n\t\txml_parser_generator/module_template.py.in \\\n\t\txml_parser_generator/make_parser.py\n\tpython3 xml_parser_generator/setuptools_builder.py\n\n.PHONY: parser\nparser: $(GENERATED_MOD)\n\n.PHONY: format-parser\nformat-parser:\n\truff format $(GENERATED_MOD)\n\n.PHONY: distclean\ndistclean: clean\n\t$(MAKE) -C documentation clean\n\t$(RM) $(GENERATED_MOD)\n\n.PHONY: clean\nclean:\n\t$(MAKE) -C examples/doxygen $@\n\t$(MAKE) -C examples/tinyxml $@\n\t$(MAKE) -C examples/specific $@\n\n.PHONY: test\ntest: $(GENERATED_MOD)\n\tcd tests && python3 -m pytest -v --maxfail=1\n\n.PHONY: dev-test\ndev-test: $(GENERATED_MOD)\n\tcd tests && PYTHONPATH=../:$(PYTHONPATH) python3 -m pytest -v\n\n.PHONY: ruff\nruff:\n\truff check\n\truff format\n\n.PHONY: type-check\ntype-check: $(GENERATED_MOD)\n\tmypy --warn-redundant-casts --warn-unused-ignores breathe tests\n"
},
{
"path": "README.rst",
"content": ".. image:: https://www.breathe-doc.org/img/logo.svg\n :align: center\n :alt: Breathe logo\n :width: 200\n :height: 200\n :target: https://www.breathe-doc.org\n\nBreathe\n=======\n\n**Your technical docs, beautifully integrated**\n\n.. image:: https://github.com/breathe-doc/breathe/actions/workflows/unit_tests.yml/badge.svg\n :target: https://github.com/breathe-doc/breathe/actions/workflows/unit_tests.yml\n :alt: Build Status\n\nWebsite_ • Documentation_ • Sponsor_\n\n**Sponsor**: If you benefit from using Breathe as a company or an individual, you\ncan financially support the Breathe project with recurring or one off\ncontributions via `Open Collective `_.\n\n.. _Website: https://www.breathe-doc.org/\n.. _Documentation: https://breathe.readthedocs.io/en/latest/\n.. _Sponsor: https://opencollective.com/breathe\n\n----\n\nBreathe is a Sphinx plugin providing beautifully integrated Doxygen output in\nyour user-facing documentation. It allows you to combine Doxygen's excellent\ntechnical understanding of your code base with the superb long form\ndocumentation output of the Sphinx system.\n\nFor Packagers\n-------------\n\n- Breathe packages on PyPI are PGP signed for Breathe >= v4.28.0.\n- Breathe tarballs on GitHub are PGP signed for Breathe >= v4.29.0.\n\nDownload\n--------\n\nBreathe is available from github and `PyPI, the Python Package Index\n`_. It can be installed with::\n\n pip install breathe\n\nDocumentation\n-------------\n\nThe documentation is available `here `__. Thank\nyou to the people running `Read the Docs `_ for such an\nexcellent service.\n\nThe source for the documentation is in the ``documentation`` folder if you want\nto built it and read it locally.\n\nTesting\n-------\n\nThe testsuite can be run with::\n\n make dev-test\n\nThe documentation also does a good effort of covering the available\nfunctionality with different examples. To build the documentation, run::\n\n make\n\nThis will run doxygen over the example code and then run the Breathe\ndocumentation. View the results at::\n\n documentation/build/html/index.html\n\nFurther to this if you want to compare the current documentation output against\na previous state in order to check for regressions there is a ``compare`` script\nin the ``documentation`` folder. It takes two arguments which are two commit\nreferences that you'd like to compare. This means that all your changes have to\nbe committed first. Also the script does not resolve state dependent references\nlike ``HEAD`` so provide concrete commit references like sha1s or branch names.\nA typical example is to compare your current branch output to master::\n\n # Make sure all your changes are committed first\n cd documentation\n ./compare master my-branch\n\nThis will do a checkout and build at each commit and then run ``meld`` against\nthe resulting directories so you can see the differences introduced by your\nbranch.\n\nRequirements\n------------\n\nBreathe requires Python 3.9+, Sphinx 7.2+, and Doxygen 1.9.2+.\n\nMailing List Archives\n---------------------\n\nThe archive for the Google groups list can be found\n`here `__.\n\nThe previous mailing list was on `librelist.com `__ and the\narchives are available `here `__.\n\nPlease post new questions as GitHub issues.\n\nProjects Using Breathe\n----------------------\n\nExamples of projects that use Breathe:\n\n- `PyTorch `_\n- `OpenPilot `_\n- `XGBoost `_\n- `NumPy `_\n- `Mozilla's DeepSpeech `_\n- `Microsoft's LightGBM `_\n- `PyBind11 `_\n- `Ceph `_\n- `Apache Arrow `_\n- `LVGL `_\n- `Espressif IoT Development Framework `_\n- `Zephyr Project `_\n- `Plaid ML `_\n- `Sony's Neural Network Libraries `_\n- `fmt `_\n\nRelease\n-------\n\n1. Update `CHANGELOG.rst` and create the git tag (`vX.Y.Z`).\n2. Push the tag to GitHub.\n3. The `create-release.yml` workflow will publish the release to PyPI.\n4. Go to https://github.com/breathe-doc/breathe/tags, select the new tag,\n and click the \"Create release from tag\" button to publish a GitHub release.\n\nMaintainers\n-----------\n\nBreathe is currently maintained by `vermeeren `_ & `jakobandersen `_\nand was formerly maintained by `michaeljones `_\n& `vitaut `_.\n\nSee `CONTRIBUTORS `_ for the full list.\n\nAcknowledgements\n----------------\n\n- Dimitri van Heesch for `Doxygen `_.\n- Georg Brandl for `Sphinx `_.\n- David Goodger for `Docutils `_ and reStructuredText.\n\nChangelog\n---------\n\nSee the `CHANGELOG.rst\n`_\n"
},
{
"path": "breathe/README.rst",
"content": "\nbreathe\n=======\n\n- **Subpackages**\n\n - **directive** - Contains some rst directive definitions. These were split out\n of `directives.py` when it started to become too large.\n - **finder** - Provides classes for finding nodes within the set of xml\n files generated by doxygen. Finders are generally used in the `run` methods of\n the directives to find the xml node which is then passed to the renderer to\n create the output.\n - **renderer** - Provides classes for rendering an xml node from the doxygen xml\n into docutils rst nodes which can be used by Sphinx. Breathe should ideally\n only produce rst nodes and not concern itself with the final output (html,\n latex, etc.)\n\n- **Submodules**\n\n - **directives** - Contains the definitions of some of the directives. The rest\n are in the files in the `directive` folder. It also contains all the set up\n code which registers with Sphinx and wires together all the various factories.\n - **parser** - Contains code for parsing the doxygen xml into a tree of Python\n objects. Most of its content is imported from `_parser`, which is generated\n automatically when Breathe is built.\n - **process** - Contains the code responsible for running the `doxygen` process\n when using the `autodoxygen` directives.\n - **project** - Handles the concept of a `Project` which is the breathe term for\n a folder full of doxygen xml files.\n - **exception** - Contains the base class for all custom exceptions.\n"
},
{
"path": "breathe/__init__.py",
"content": "from __future__ import annotations\n\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n from sphinx.application import Sphinx\n\n__version__ = \"5.0.0a5\"\n\n\ndef setup(app: Sphinx):\n from breathe.directives.setup import setup as directive_setup\n from breathe.file_state_cache import setup as file_state_cache_setup\n from breathe.renderer.sphinxrenderer import setup as renderer_setup\n\n directive_setup(app)\n file_state_cache_setup(app)\n renderer_setup(app)\n\n return {\"version\": __version__, \"parallel_read_safe\": True, \"parallel_write_safe\": True}\n"
},
{
"path": "breathe/apidoc.py",
"content": "\"\"\"\nbreathe.apidoc\n~~~~~~~~~~~~~~\n\nParses doxygen XML tree looking for C/C++ modules and creates ReST files\nappropriately to create code documentation with Sphinx. It also creates a\nmodules index (See TYPEDICT below.).\n\nThis is derived from the \"sphinx-autopackage\" script, which is:\nCopyright 2008 Société des arts technologiques (SAT),\nhttp://www.sat.qc.ca/\n\n:copyright: Originally by Sphinx Team, C++ modifications by Tatsuyuki Ishi\n:license: BSD, see LICENSE for details.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport os\nimport sys\nimport xml.etree.ElementTree\nfrom pathlib import Path\n\nfrom breathe import __version__\n\n# Reference: Doxygen XSD schema file, CompoundKind only\n# Only what breathe supports are included\n# Translates identifier to English\nTYPEDICT = {\n \"class\": \"Class\",\n \"interface\": \"Interface\",\n \"struct\": \"Struct\",\n \"union\": \"Union\",\n \"file\": \"File\",\n \"namespace\": \"Namespace\",\n \"group\": \"Group\",\n}\n\n# Types that accept the :members: option.\nMEMBERS_TYPES = [\"class\", \"group\", \"interface\", \"namespace\", \"struct\"]\n\n\ndef print_info(msg, args):\n if not args.quiet:\n print(msg)\n\n\ndef write_file(name, text, args):\n \"\"\"Write the output file for module/package .\"\"\"\n fname = Path(args.destdir, f\"{name}.{args.suffix}\")\n if args.dryrun:\n print_info(\"Would create file %s.\" % fname, args)\n return\n if not args.force and fname.is_file():\n print_info(\"File %s already exists, skipping.\" % fname, args)\n else:\n print_info(\"Creating file %s.\" % fname, args)\n fname.parent.mkdir(parents=True, exist_ok=True)\n try:\n orig = fname.read_text(encoding=\"utf-8\")\n if orig == text:\n print_info(\"File %s up to date, skipping.\" % fname, args)\n return\n except FileNotFoundError:\n # Don't mind if it isn't there\n pass\n fname.write_text(text, encoding=\"utf-8\")\n\n\ndef format_heading(level, text):\n \"\"\"Create a heading of [1, 2 or 3 supported].\"\"\"\n underlining = [\"=\", \"-\", \"~\"][level - 1] * len(text)\n return \"%s\\n%s\\n\\n\" % (text, underlining)\n\n\ndef format_directive(package_type, package, args):\n \"\"\"Create the breathe directive and add the options.\"\"\"\n directive = \".. doxygen%s:: %s\\n\" % (package_type, package)\n if args.project:\n directive += \" :project: %s\\n\" % args.project\n if args.members and package_type in MEMBERS_TYPES:\n directive += \" :members:\\n\"\n return directive\n\n\ndef create_package_file(package, package_type, package_id, args):\n \"\"\"Build the text of the file and write the file.\"\"\"\n # Skip over types that weren't requested\n if package_type not in args.outtypes:\n return\n text = format_heading(1, \"%s %s\" % (TYPEDICT[package_type], package))\n text += format_directive(package_type, package, args)\n\n write_file(Path(package_type, package_id), text, args)\n\n\ndef create_modules_toc_file(key, value, args):\n \"\"\"Create the module's index.\"\"\"\n if not Path(args.destdir, key).is_dir():\n return\n text = format_heading(1, \"%s list\" % value)\n text += \".. toctree::\\n\"\n text += \" :glob:\\n\\n\"\n text += \" %s/*\\n\" % key\n\n write_file(\"%slist\" % key, text, args)\n\n\ndef recurse_tree(args):\n \"\"\"\n Look for every file in the directory tree and create the corresponding\n ReST files.\n \"\"\"\n index = xml.etree.ElementTree.parse(Path(args.rootpath, \"index.xml\"))\n\n # Assuming this is a valid Doxygen XML\n for compound in index.getroot():\n create_package_file(\n compound.findtext(\"name\"), compound.get(\"kind\"), compound.get(\"refid\"), args\n )\n\n\nclass TypeAction(argparse.Action):\n def __init__(self, option_strings, dest, **kwargs):\n super().__init__(option_strings, dest, **kwargs)\n self.default = TYPEDICT.keys()\n self.metavar = \",\".join(TYPEDICT.keys())\n\n def __call__(self, parser, namespace, values, option_string=None):\n assert isinstance(values, str)\n value_list = values.split(\",\")\n for value in value_list:\n if value not in TYPEDICT:\n raise ValueError(\"%s not a valid option\" % value)\n setattr(namespace, self.dest, value_list)\n\n\ndef main():\n \"\"\"Parse and check the command line arguments.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"\"\"\\\nParse XML created by Doxygen in and create one reST file with\nbreathe generation directives per definition in the .\n\nNote: By default this script will not overwrite already created files.\"\"\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n\n parser.add_argument(\n \"-o\",\n \"--output-dir\",\n action=\"store\",\n dest=\"destdir\",\n help=\"Directory to place all output\",\n required=True,\n )\n parser.add_argument(\n \"-f\", \"--force\", action=\"store_true\", dest=\"force\", help=\"Overwrite existing files\"\n )\n parser.add_argument(\n \"-m\",\n \"--members\",\n action=\"store_true\",\n dest=\"members\",\n help=\"Include members for types: %s\" % MEMBERS_TYPES,\n )\n parser.add_argument(\n \"-n\",\n \"--dry-run\",\n action=\"store_true\",\n dest=\"dryrun\",\n help=\"Run the script without creating files\",\n )\n parser.add_argument(\n \"-T\",\n \"--no-toc\",\n action=\"store_true\",\n dest=\"notoc\",\n help=\"Don't create a table of contents file\",\n )\n parser.add_argument(\n \"-s\",\n \"--suffix\",\n action=\"store\",\n dest=\"suffix\",\n help=\"file suffix (default: rst)\",\n default=\"rst\",\n )\n parser.add_argument(\n \"-p\",\n \"--project\",\n action=\"store\",\n dest=\"project\",\n help=\"project to add to generated directives\",\n )\n parser.add_argument(\n \"-g\",\n \"--generate\",\n action=TypeAction,\n dest=\"outtypes\",\n help=\"types of output to generate, comma-separated list\",\n )\n parser.add_argument(\n \"-q\", \"--quiet\", action=\"store_true\", dest=\"quiet\", help=\"suppress informational messages\"\n )\n parser.add_argument(\n \"--version\", action=\"version\", version=\"Breathe (breathe-apidoc) %s\" % __version__\n )\n parser.add_argument(\"rootpath\", type=str, help=\"The directory contains index.xml\")\n args = parser.parse_args()\n\n args.suffix = args.suffix.removeprefix(\".\")\n if not os.path.isdir(args.rootpath):\n print(\"%s is not a directory.\" % args.rootpath, file=sys.stderr)\n sys.exit(1)\n if \"index.xml\" not in os.listdir(args.rootpath):\n print(\"%s does not contain a index.xml\" % args.rootpath, file=sys.stderr)\n sys.exit(1)\n if not os.path.isdir(args.destdir):\n if not args.dryrun:\n os.makedirs(args.destdir)\n args.rootpath = os.path.abspath(args.rootpath)\n recurse_tree(args)\n if not args.notoc:\n for key in args.outtypes:\n create_modules_toc_file(key, TYPEDICT[key], args)\n\n\n# So program can be started with \"python -m breathe.apidoc ...\"\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "breathe/cpp_util.py",
"content": "from __future__ import annotations\n\nimport re\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n from collections.abc import Iterator\n\nRE_NAME_PART = re.compile(r\"([<>()[\\]]|::)\")\n\n\ndef _check_pair(dest: list[str], tokens: Iterator[str], start: str, end: str) -> bool:\n if dest[-1] == start:\n for tok in tokens:\n dest.append(tok)\n if tok == end:\n break\n # If we're inside angle brackets, we assume \"<\" and \">\" are brackets\n # and not comparison operators. Once we're inside other brackets, we\n # only need to worry about recursive brackets and can ignore the\n # other types.\n if start == \"<\":\n _check_all_pairs(dest, tokens)\n else:\n _check_pair(dest, tokens, start, end)\n return True\n return False\n\n\ndef _check_all_pairs(dest: list[str], tokens: Iterator[str]) -> None:\n if not _check_pair(dest, tokens, \"<\", \">\"):\n if not _check_pair(dest, tokens, \"(\", \")\"):\n if not _check_pair(dest, tokens, \"[\", \"]\"):\n _check_pair(dest, tokens, \"{\", \"}\")\n\n\ndef split_name(name: str) -> list[str]:\n \"\"\"Split a qualified C++ name into the namespace components.\n\n E.g. turn \"A