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,47 +1,76 @@
-name: build the documentation
-on: [push, pull_request]
+name: Build documentation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  DOXYGEN_VERSION: 1.9.4
+  FORCE_COLOR: "1"
+
 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-
-
-      - name: set up python
-        uses: actions/setup-python@v1
-
-      - name: install dependencies
-        run: |
-          pip install -r requirements/development.txt
-          sudo apt-get -y update
-          sudo apt-get -y install graphviz libclang1-11 libclang-cpp11
-
-      - name: install doxygen from SF binary archives
-        env:
-          DOXYGEN_VERSION: 1.9.4
-        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
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+        cache: 'pip'
+
+    - name: Install apt dependencies
+      run: |
+        sudo apt-get -y update
+        sudo apt-get -y install graphviz libclang1-11 libclang-cpp11
+
+    - 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: |
+        cd doxygen-bin-arc
+        if test -d doxygen; then
+          cd doxygen
+        else
           gunzip doxygen.tar.gz
           tar xf doxygen.tar
-          cd doxygen-$DOXYGEN_VERSION
-          sudo make install
-
-      - name: build the documentation
-        run: |
-          make html
-          rm documentation/build/html/.buildinfo
-
-      - uses: actions/upload-artifact@v2
-        with:
-          name: docs build artifacts
-          path: |
-            documentation/build/html
-            examples/*/*/xml
+          cd doxygen-${{ env.DOXYGEN_VERSION }}
+        fi
+        sudo make install
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .[docs]
+
+    - name: Build the documentation
+      run: |
+        make html
+        rm documentation/build/html/.buildinfo
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: docs build artifacts
+        path: |
+          documentation/build/html
+          examples/*/*/xml

.github/workflows/lint.yml

@@ -1,33 +1,85 @@
-name: lint
-on: [push, pull_request]
+name: Lint source code
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+
 jobs:
-  build:
+  black:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install "black==22.3.0"
+    - name: Format with black
+      run: black --check .
+
+  flake8:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade "flake8>=6"
+    - name: Lint with flake8
+      run: flake8 breathe
+
+  mypy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install dependencies
+      # "--editable" is needed so that _parser.py is placed in the local folder
+      # where pytest will import from
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --editable ".[lint]"
+    - name: Type check with mypy
+      run: mypy --warn-redundant-casts --warn-unused-ignores breathe tests
 
+  twine:
     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-
-      - name: set up python
-        uses: actions/setup-python@v1
-
-      - name: install dependencies
-        run: |
-          pip install -r requirements/development.txt
-
-      - name: lint the source code
-        run: make flake8
-
-      - name: check source code formatting
-        run: make black
-
-      - name: type check the source code
-        run: make type-check
-
-      - name: check version numbers are in sync
-        run: make version-check
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade twine build
+    - name: Lint with twine
+      run: |
+        python -m build .
+        twine check dist/*