Improve sympde

.github/workflows/documentation.yml

@@ -0,0 +1,81 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'README.rst'
+      - 'doc/**'
+      - 'sympde/**.py'
+      - 'pyproject.toml'
+      - '.github/workflows/documentation.yml'
+
+  pull_request:
+    branches: [ master ]
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.10'
+        cache: 'pip'
+        cache-dependency-path: |
+          pyproject.toml
+
+    - name: Upgrade pip, setuptools, and wheel
+      run: |
+        pip install --upgrade pip setuptools wheel
+
+    - name: Install project and documentation dependencies
+      run: |
+        pip install .[docs]
+        pip freeze
+
+    - name: Run documentation examples
+      run: |
+        for example in doc/examples/*.py; do
+          python "$example"
+        done
+
+    - name: Make the Sphinx documentation
+      run: >-
+        python -m sphinx -W --keep-going
+        -b html doc doc/_build/html
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: 'doc/_build/html'
+
+  deploy_docs:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs: build_docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.github/workflows/testing.yml

@@ -0,0 +1,129 @@
+# This workflow installs SymPDE and runs its tests with supported Python versions.
+# It follows the testing layout used by Psydac while omitting Psydac-specific
+# MPI, HDF5, PETSc, and example jobs.
+
+name: Unit tests
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'sympde/**'
+      - 'pyproject.toml'
+      - '.github/workflows/testing.yml'
+
+  pull_request:
+    branches: [ master ]
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-24.04, macos-14 ]
+        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13', '3.14' ]
+        isMerge:
+          - ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        exclude:
+          - { isMerge: false, python-version: '3.9',  os:     macos-14 }
+          - { isMerge: false, python-version: '3.10', os:     macos-14 }
+          - { isMerge: false, python-version: '3.11', os: ubuntu-24.04 }
+          - { isMerge: false, python-version: '3.12', os:     macos-14 }
+          - { isMerge: false, python-version: '3.13', os: ubuntu-24.04 }
+          - { isMerge: false, python-version: '3.14', os:     macos-14 }
+
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: |
+          pyproject.toml
+
+    - name: Upgrade pip, setuptools, and wheel
+      run: |
+        pip install --upgrade pip setuptools wheel
+
+    - name: Install project
+      run: |
+        pip install .[test]
+        pip freeze
+
+    - name: Initialize test directory
+      run: |
+        mkdir scratch
+
+    - name: Run coverage tests on macOS
+      if: matrix.os == 'macos-14'
+      working-directory: ./scratch
+      run: >-
+        pytest -n auto --dist loadgroup
+        --cov sympde --cov-report term-missing --cov-report xml
+        --pyargs sympde -ra
+
+    - name: Run tests on Ubuntu
+      if: matrix.os == 'ubuntu-24.04'
+      working-directory: ./scratch
+      run: >-
+        pytest -n auto --dist loadgroup
+        --pyargs sympde -ra
+
+    - name: Upload coverage report
+      if: matrix.os == 'macos-14'
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report-python-${{ matrix.python-version }}
+        path: scratch/coverage.xml
+
+    - name: Print detailed coverage results on macOS
+      if: matrix.os == 'macos-14'
+      working-directory: ./scratch
+      run: |
+        coverage report --ignore-errors --show-missing --sort=cover
+
+  minimum-sympy:
+    name: Ubuntu / Python 3.11 / SymPy 1.12
+    runs-on: ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.11'
+        cache: 'pip'
+        cache-dependency-path: |
+          pyproject.toml
+
+    - name: Upgrade pip, setuptools, and wheel
+      run: |
+        pip install --upgrade pip setuptools wheel
+
+    - name: Install project with minimum SymPy
+      run: |
+        pip install .[test] 'sympy == 1.12'
+        pip freeze
+
+    - name: Initialize test directory
+      run: |
+        mkdir scratch
+
+    - name: Run tests
+      working-directory: ./scratch
+      run: >-
+        pytest -n auto --dist loadgroup
+        --pyargs sympde -ra

README.rst

@@ -1,7 +1,7 @@
 SymPDE
 ======
 
-|CI status|  |binder|  |docs|
+|CI status|  |docs|
 
 **SymPDE** is a symbolic calculus library for partial differential equations and variational forms.
 It can be used to have similar capabilities as the fenics_ project, by extending and writing your own *printing* functions.
@@ -66,15 +66,38 @@ To check out a specific branch/tag/commit named ``<TAG>``, just use ``git checko
 
   In order to make changes to the library, and see these changes when the package is imported, SymPDE should be installed in **editable** mode::
 
-    python3 -m pip install --editable .
+    python3 -m pip install --editable ".[test]"
+
+Public API
+^^^^^^^^^^
+
+User-facing objects can be imported from the flat, explicit API without
+knowing which internal module defines them::
+
+  from sympde.api import Cube, Mapping, Constant
+  from sympde.api import ScalarFunctionSpace, VectorFunctionSpace, elements_of
+  from sympde.api import BilinearForm, LinearForm, Norm
+
+Running the tests
+^^^^^^^^^^^^^^^^^
+
+The complete test suite can be run from any directory with::
+
+  python3 -m pytest -n auto --dist loadgroup --pyargs sympde -ra
+
+The documentation dependencies are installed separately and the HTML pages
+are built with warnings treated as errors::
+
+  python3 -m pip install --editable ".[docs]"
+  python3 -m sphinx -W --keep-going -b html doc doc/_build/html
 
 
 For developers
 **************
 
 Because many important features of SymPDE are only tested in Psydac, new PRs should also be tested against the test suite of Psydac.
 This can be done by opening a PR in Psydac, where the only change consists of installing the corresponding branch of SymPDE.
-To achieve this, one just needs to modify the line corresponding to ``sympde`` in the ``pyproject.yaml`` file.
+To achieve this, one just needs to modify the line corresponding to ``sympde`` in the ``pyproject.toml`` file.
 
 For instance, to test a new SymPDE branch called ``my_feature``, one should write
 
@@ -94,14 +117,10 @@ Do not forget the comma at the end of the line, as this is an item in a list.
 Also, pay attention to the words ``head`` and ``tags`` in the path: the former is used for Git branches, the latter is used for Git tags (which may or may not correspond to GitHub releases).
 
 
-.. |CI status| image:: https://github.com/pyccel/sympde/actions/workflows/continuous-integration.yml/badge.svg?branch=master&event=push
+.. |CI status| image:: https://github.com/pyccel/sympde/actions/workflows/testing.yml/badge.svg?branch=master&event=push
    :alt: CI status
-   :target: https://github.com/pyccel/sympde/actions/workflows/continuous-integration.yml
+   :target: https://github.com/pyccel/sympde/actions/workflows/testing.yml
 
-.. |docs| image:: https://readthedocs.org/projects/sympde/badge/?version=latest
+.. |docs| image:: https://github.com/pyccel/sympde/actions/workflows/documentation.yml/badge.svg
    :alt: Documentation Status
-   :target: http://sympde.readthedocs.io/en/latest/?badge=latest
-
-.. |binder| image:: https://mybinder.org/badge_logo.svg
-   :alt: Run notebooks in Binder
-   :target: https://mybinder.org/v2/gh/pyccel/sympde/master
+   :target: https://github.com/pyccel/sympde/actions/workflows/documentation.yml