Performance improvements, new tests, more typing annotations and miscellaneous fixes

.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,59 @@
 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
+        # at some point actions/cache/restore@4 started unpacking doxygen.tar.gz
+        # automatically and I don't know why -- Rouslan
         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
-          gunzip doxygen.tar.gz
-          tar xf doxygen.tar
-          cd doxygen-$DOXYGEN_VERSION
+          cd doxygen-bin-arc
+          if test -d doxygen; then
+            cd doxygen
+          else
+            gunzip doxygen.tar.gz
+            tar xf doxygen.tar
+            cd doxygen-${{ env.DOXYGEN_VERSION }}
+          fi
           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,64 +1,96 @@
 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'
           - '5.0.2'
           - '5.1.1'
           - '5.3.0'
           - '6.1.3'
+          - '7.2.6'
+          # version 7.3 broke up the domain modules into packages, changing
+          # where some classes had to be imported from
+          - '7.3.0'
           - git+https://github.com/sphinx-doc/sphinx.git@master
         exclude:
-          # avoid bug in following configurations
-          # sphinx/util/typing.py:37: in <module>
-          #     from types import Union as types_Union
-          # ImportError: cannot import name 'Union' from 'types'
-          - python-version: '3.10'
-            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 7.2 and up isn't compatible with Python 3.8
+          - python-version: '3.8'
+            sphinx-version: '7.2.6'
+          - python-version: '3.8'
+            sphinx-version: '7.3.0'
+          - python-version: '3.8'
             sphinx-version: git+https://github.com/sphinx-doc/sphinx.git@master
-          - python-version: '3.7'
-            sphinx-version: '6.1.3'
 
     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
+
+      # the latest sphinxcontrib- packages don't work with Sphinx version 4
+      - name: install sphinx from PyPI with compatible versions of sphinxcontrib- packages
+        if: ${{ startsWith(matrix.sphinx-version, '4.') }}
+        run: >
+          pip install -Iv
+          Sphinx==${{ matrix.sphinx-version }}
+          sphinxcontrib-applehelp==1.0.4
+          sphinxcontrib-devhelp==1.0.2
+          sphinxcontrib-htmlhelp==2.0.1
+          sphinxcontrib-serializinghtml==1.1.5
+          sphinxcontrib-qthelp==1.0.3
+
+      - name: install sphinx from PyPI
+        if: ${{ ! startsWith(matrix.sphinx-version, 'git') && ! startsWith(matrix.sphinx-version, '4.') }}
+        run: |
+          pip install -Iv Sphinx==${{ matrix.sphinx-version }}
+
+      - name: install sphinx from git
+        if: startsWith(matrix.sphinx-version, 'git')
+        run: |
+          pip install ${{ matrix.sphinx-version }}
+
+      - 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 sphinx from PyPI or from git
+      - name: install Doxygen
+        # at some point actions/cache/restore@4 started unpacking doxygen.tar.gz
+        # automatically and I don't know why -- Rouslan
         run: |
-          if echo "${{ matrix.sphinx-version }}"|grep -q git; then
-              pip install ${{ matrix.sphinx-version }}
+          cd doxygen-bin-arc
+          if test -d doxygen; then
+            cd doxygen
           else
-              pip install -Iv Sphinx==${{ matrix.sphinx-version }}
+            gunzip doxygen.tar.gz
+            tar xf doxygen.tar
+            cd doxygen-${{ matrix.doxygen-version }}
           fi
+          sudo make install
 
-      - name: install dependencies
+      - 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)