Support members in a Doxygen 1.9.7 group

.github/FUNDING.yml

@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+github: breathe-doc
 patreon: # Replace with a single Patreon username
 open_collective: breathe
 ko_fi: # Replace with a single Ko-fi username

.github/workflows/cache_doxygen.yml

@@ -0,0 +1,33 @@
+name: download and cache Doxygen
+on:
+  workflow_call
+jobs:
+  install:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: linux-doxygen-${{ matrix.doxygen-version }}-cache
+    strategy:
+      fail-fast: false
+      matrix:
+        doxygen-version: ['1.9.4', '1.9.7']
+    steps:
+      - uses: actions/cache/restore@v4
+        id: cache-doxygen
+        with:
+          path: doxygen-bin-arc
+          key: ${{ runner.os }}-doxygen-${{ matrix.doxygen-version }}
+          lookup-only: true
+          restore-keys: |
+            ${{ runner.os }}-doxygen-
+
+      - name: download Doxygen from SF binary archives
+        if: steps.cache-doxygen.outputs.cache-hit != 'true'
+        run: |
+          mkdir doxygen-bin-arc && cd doxygen-bin-arc
+          curl -L https://sourceforge.net/projects/doxygen/files/rel-${{ matrix.doxygen-version }}/doxygen-${{ matrix.doxygen-version }}.linux.bin.tar.gz > doxygen.tar.gz
+
+      - uses: actions/cache/save@v4
+        if: steps.cache-doxygen.outputs.cache-hit != 'true'
+        with:
+          path: doxygen-bin-arc
+          key: ${{ steps.cache-doxygen.outputs.cache-primary-key }}

.github/workflows/documentation.yml

@@ -1,45 +1,53 @@
 name: build the documentation
 on: [push, pull_request]
+env:
+  DOXYGEN_VERSION: 1.9.4
 jobs:
-  build:
+  cache-doxygen:
+    uses: ./.github/workflows/cache_doxygen.yml
 
+  build:
+    needs: cache-doxygen
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/cache@v1
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
+      - uses: actions/checkout@v4
       - name: set up python
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
+        with:
+          cache: 'pip'
+          cache-dependency-path: |
+            requirements/development.txt
+            requirements/production.txt
 
-      - name: install dependencies
+      - name: install dependencies and build extension module
         run: |
-          pip install -r requirements/development.txt
           sudo apt-get -y update
           sudo apt-get -y install graphviz libclang1-11 libclang-cpp11
+          pip install -r requirements/development.txt
+          pip install --editable .
 
-      - name: install doxygen from SF binary archives
-        env:
-          DOXYGEN_VERSION: 1.9.4
+      - uses: actions/cache/restore@v4
+        id: cache-doxygen
+        with:
+          path: doxygen-bin-arc
+          fail-on-cache-miss: true
+          key: ${{ runner.os }}-doxygen-${{ env.DOXYGEN_VERSION }}
+
+      - name: install Doxygen
         run: |
-          mkdir doxygen-bin-arc && cd doxygen-bin-arc
-          curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz
+          cd doxygen-bin-arc
           gunzip doxygen.tar.gz
           tar xf doxygen.tar
-          cd doxygen-$DOXYGEN_VERSION
+          cd doxygen-${{ env.DOXYGEN_VERSION }}
           sudo make install
 
       - name: build the documentation
         run: |
           make html
           rm documentation/build/html/.buildinfo
 
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: docs build artifacts
           path: |

.github/workflows/lint.yml

@@ -7,14 +7,13 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/cache@v1
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
       - name: set up python
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
+        with:
+          cache: 'pip'
+          cache-dependency-path: |
+            requirements/development.txt
+            requirements/production.txt
 
       - name: install dependencies
         run: |

.github/workflows/unit_tests.yml

@@ -1,16 +1,18 @@
 name: unit tests
 on: [push, pull_request]
 jobs:
-  build:
+  cache-doxygen:
+    uses: ./.github/workflows/cache_doxygen.yml
 
+  build:
+    needs: cache-doxygen
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        doxygen-version: ['1.9.4', '1.9.7']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
         sphinx-version:
-          - '4.0.3'
-          - '4.1.2'
           - '4.2.0'
           - '4.3.2'
           - '4.5.0'
@@ -20,6 +22,10 @@ jobs:
           - '6.1.3'
           - git+https://github.com/sphinx-doc/sphinx.git@master
         exclude:
+          # the git version isn't compatible with Python 3.8
+          - python-version: '3.8'
+            sphinx-version: git+https://github.com/sphinx-doc/sphinx.git@master
+
           # avoid bug in following configurations
           # sphinx/util/typing.py:37: in <module>
           #     from types import Union as types_Union
@@ -28,25 +34,25 @@ jobs:
             sphinx-version: '4.0.3'
           - python-version: '3.10'
             sphinx-version: '4.1.2'
-
-          # Sphinx has removed support for Python 3.7, Breathe will follow.
-          - python-version: '3.7'
-            sphinx-version: git+https://github.com/sphinx-doc/sphinx.git@master
-          - python-version: '3.7'
-            sphinx-version: '6.1.3'
+          - python-version: '3.11'
+            sphinx-version: '4.0.3'
+          - python-version: '3.11'
+            sphinx-version: '4.1.2'
+          - python-version: '3.12'
+            sphinx-version: '4.0.3'
+          - python-version: '3.12'
+            sphinx-version: '4.1.2'
 
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/cache@v1
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
       - name: set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: |
+            requirements/development.txt
+            requirements/production.txt
 
       - name: install sphinx from PyPI or from git
         run: |
@@ -56,9 +62,25 @@ jobs:
               pip install -Iv Sphinx==${{ matrix.sphinx-version }}
           fi
 
-      - name: install dependencies
+      - uses: actions/cache/restore@v4
+        id: cache-doxygen
+        with:
+          path: doxygen-bin-arc
+          fail-on-cache-miss: true
+          key: ${{ runner.os }}-doxygen-${{ matrix.doxygen-version }}
+
+      - name: install Doxygen
+        run: |
+          cd doxygen-bin-arc
+          gunzip doxygen.tar.gz
+          tar xf doxygen.tar
+          cd doxygen-${{ matrix.doxygen-version }}
+          sudo make install
+
+      - name: install dependencies and build extension module
         run: |
           pip install -r requirements/development.txt
+          pip install --editable .
 
       - name: run the unit tests
         run: make dev-test

.gitignore

@@ -48,3 +48,6 @@ com_crashlytics_export_strings.xml
 # modified by build process
 examples/doxygen/example.tag
 examples/specific/dot_graphs/xml/dotfile.dot
+
+# generated in editable install
+/breathe/_parser.py

MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include xml_parser_generator *.py *.in *.json 
+include requirements/*.txt tests/*.py
+graft tests/data
+exclude breathe/_parser.py
+global-exclude *.py[cod]

Makefile

@@ -1,3 +1,5 @@
+RM        		= rm -f
+GENERATED_MOD	= breathe/_parser.py
 
 .PHONY: all
 all: html pdf
@@ -16,9 +18,16 @@ data:
 	$(MAKE) -C examples/tinyxml all
 	$(MAKE) -C examples/specific all
 
+$(GENERATED_MOD): \
+		xml_parser_generator/schema.json \
+		xml_parser_generator/module_template.py.in \
+		xml_parser_generator/make_parser.py
+	python3 xml_parser_generator/setuptools_builder.py
+
 .PHONY: distclean
 distclean: clean
 	$(MAKE) -C documentation clean
+	$(RM) $(GENERATED_MOD)
 
 .PHONY: clean
 clean:
@@ -31,7 +40,7 @@ test:
 	cd tests && python3 -m pytest -v
 
 .PHONY: dev-test
-dev-test:
+dev-test: $(GENERATED_MOD)
 	cd tests && PYTHONPATH=../:$(PYTHONPATH) python3 -m pytest -v
 
 .PHONY: flake8
@@ -43,7 +52,7 @@ black:
 	black --check .
 
 .PHONY: type-check
-type-check:
+type-check: $(GENERATED_MOD)
 	mypy --warn-redundant-casts --warn-unused-ignores breathe tests
 
 .PHONY: version-check

README.rst

@@ -98,7 +98,7 @@ branch.
 Requirements
 ------------
 
-Breathe requires Python 3.6+, Sphinx 4.0+ and Doxygen 1.8+.
+Breathe requires Python 3.8+, Sphinx 4.0+ and Doxygen 1.8+.
 
 Mailing List Archives
 ---------------------

breathe/README.rst

@@ -6,9 +6,6 @@ breathe
 
   - **directive** - Contains some rst directive definitions. These were split out
     of `directives.py` when it started to become too large.
-  - **parser** - Contains code for parsing the doxygen xml into a tree of Python
-    objects. The vast majority of the code is autogenerated but there are now
-    small but significant tweaks which means we don't regenerate it.
   - **finder** - Provides classes for finding nodes within the set of xml
     files generated by doxygen. Finders are generally used in the `run` methods of
     the directives to find the xml node which is then passed to the renderer to
@@ -23,6 +20,9 @@ breathe
   - **directives** - Contains the definitions of some of the directives. The rest
     are in the files in the `directive` folder. It also contains all the set up
     code which registers with Sphinx and wires together all the various factories.
+  - **parser** - Contains code for parsing the doxygen xml into a tree of Python
+    objects. Most of its content is imported from `_parser`, which is generated
+    automatically when Breathe is built.
   - **process** - Contains the code responsible for running the `doxygen` process
     when using the `autodoxygen` directives.
   - **project** - Handles the concept of a `Project` which is the breathe term for

breathe/__init__.py

@@ -1,14 +1,14 @@
-from breathe.directives.setup import setup as directive_setup
-from breathe.file_state_cache import setup as file_state_cache_setup
-from breathe.renderer.sphinxrenderer import setup as renderer_setup
-
 from sphinx.application import Sphinx
 
-# Keep in sync with setup.py __version__
+# Keep in sync with pyproject.toml "version"
 __version__ = "4.35.0"
 
 
 def setup(app: Sphinx):
+    from breathe.directives.setup import setup as directive_setup
+    from breathe.file_state_cache import setup as file_state_cache_setup
+    from breathe.renderer.sphinxrenderer import setup as renderer_setup
+
     directive_setup(app)
     file_state_cache_setup(app)
     renderer_setup(app)

breathe/apidoc.py

@@ -14,8 +14,6 @@
     :copyright: Originally by Sphinx Team, C++ modifications by Tatsuyuki Ishi
     :license: BSD, see LICENSE for details.
 """
-from __future__ import print_function
-
 import os
 import sys
 import argparse
@@ -24,13 +22,6 @@
 
 from breathe import __version__
 
-# Account for FileNotFoundError in Python 2
-# IOError is broader but will hopefully suffice
-try:
-    FileNotFoundError
-except NameError:
-    FileNotFoundError = IOError
-
 
 # Reference: Doxygen XSD schema file, CompoundKind only
 # Only what breathe supports are included
@@ -76,9 +67,10 @@ def write_file(name, text, args):
                 if orig == text:
                     print_info("File %s up to date, skipping." % fname, args)
                     return
-        except FileNotFoundError:
+        except OSError as exc:
             # Don't mind if it isn't there
-            pass
+            if exc.errno != errno.ENOENT:
+                raise
 
         with open(fname, "w") as target:
             target.write(text)
@@ -146,6 +138,7 @@ def __init__(self, option_strings, dest, **kwargs):
         self.metavar = ",".join(TYPEDICT.keys())
 
     def __call__(self, parser, namespace, values, option_string=None):
+        assert isinstance(values, str)
         value_list = values.split(",")
         for value in value_list:
             if value not in TYPEDICT: