Version 2.0 update.

.github/workflows/documentation.yml

@@ -1,111 +1,103 @@
-name: "DOCUMENTATION"
+# Workflow to build doc, upload it as artifact, and deploy it for the
+# master, main and dev branches.
+#
+# To run this check locally from the `doc` folder:
+#
+# .. code-block:: bash
+#
+#   $ sphinxdoc -v 2 -p $MODULE_DIR -n $MODULE_NAME -o $MODULE_DIR/doc
+#   $ cd $MODULE_DIR/doc
+#   $ make html-strict
+###
+name: "DocumentationBuilder"
 
 on:
   push:
     branches:
       - "master"
+      - "main"
+      - "dev"
   pull_request:
     branches:
       - "*"
+  workflow_dispatch:
+
+env:
+  MIN_PYTHON_VERSION: "3.12"
 
 jobs:
 
   build_and_deploy:
 
-    runs-on: ${{ matrix.os }}
-    if: ${{ github.ref == 'refs/heads/master' }}
+    runs-on: "ubuntu-latest"
     strategy:
       fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.12]
 
     permissions:
       contents: write
 
     steps:
+    - name: Extract branch name
+      id: extract-branch
+      shell: bash
+      run: echo "BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT
+    - name: Identify deploy type
+      id: deploy-type
+      run: |
+        if ${{ github.ref == 'refs/heads/master' ||
+            github.ref == 'refs/heads/main' }}; then
+            echo "DEPLOY_TYPE=stable" >> $GITHUB_OUTPUT
+        elif ${{ github.ref == 'refs/heads/dev' }}; then
+            echo "DEPLOY_TYPE=dev" >> $GITHUB_OUTPUT
+        else
+          echo "DEPLOY_TYPE=pr" >> $GITHUB_OUTPUT
+        fi
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         fetch-depth: 0
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+    - name: Set up Python
+      uses: actions/setup-python@v6
       with:
-        python-version: ${{ matrix.python-version }}
-    #- name: Install Latex
-    #  run: |
-    #    sudo apt install texlive-latex-extra
-    #    sudo apt install dvipng
-    - name: Install dependencies
+        python-version: ${{ env.MIN_PYTHON_VERSION }}
+        cache: "pip"
+    - name: Install Python dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install git+https://github.com/AGrigis/pysphinxdoc.git
+        pip install setuptools
         pip install --progress-bar off .
-   #     pip install -r doc/requirements.txt
+    - name: Install apt packages
+      uses: awalsh128/cache-apt-pkgs-action@latest
+      with:
+        packages: dvipng texlive-latex-base texlive-latex-extra build-essential
+        version: 1.0
+    - name: Install documentation resources
+      run: |
+        DIR=$(pwd)
+        which python
+        sphinxdoc -v 2 -p $DIR -n pysphinxdoc -o $DIR/doc
     - name: Compute documentation
       run: |
-        mkdir -p tmp/doc
         DIR=$(pwd)
-        sphinxdoc -v 2 -p . -n pysphinxdoc -o $DIR/tmp/doc
-        cd tmp/doc
-        make raw-html
-        ls source/_static
-        ls build/html/_static
-        cp -r source/_static/* build/html/_static
-        cd ../..
+        cd $DIR/doc
+        echo "Documentation folder: $DIR/doc"
+        make html-strict
+        cd $DIR
     - name: Upload documentation as an artifact
       uses: actions/upload-artifact@v4
+      env:
+        DEPLOY_TYPE: ${{ steps.deploy-type.outputs.DEPLOY_TYPE }}
       with: 
-        name: html-documentation
-        retention-days: 15
+        name: doc-${{ env.DEPLOY_TYPE }}
+        retention-days: 1
         path: |
-            tmp/doc/build/html
+            doc/_build/html
     - name: Deploy
+      env:
+        DEPLOY_TYPE: ${{ steps.deploy-type.outputs.DEPLOY_TYPE }}
+      if: env.DEPLOY_TYPE != 'pr'
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: tmp/doc/build/html
-
-  build:
-
-    runs-on: ${{ matrix.os }}
-    if: ${{ github.ref != 'refs/heads/master' }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.12]
-
-    permissions:
-      contents: write
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install Latex
-      run: |
-        sudo apt install texlive-latex-extra
-        sudo apt install dvipng
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install git+https://github.com/AGrigis/pysphinxdoc.git
-        pip install --progress-bar off .
-    #    pip install -r doc/requirements.txt
-    - name: Compute documentation
-      run: |
-        mkdir -p tmp/doc
-        DIR=$(pwd)
-        sphinxdoc -v 2 -p . -n pysphinxdoc -o $DIR/tmp/doc
-        cd tmp/doc
-        make raw-html
-        ls source/_static
-        ls build/html/_static
-        cp -r source/_static/* build/html/_static
-        cd ../..
+        publish_dir: doc/_build/html
+        destination_dir: ./${{ env.DEPLOY_TYPE }}

.github/workflows/linters.yml

@@ -0,0 +1,49 @@
+---
+# Workflow to check code format.
+#
+# To run this check locally from the repository folder:
+#
+# .. code-block:: bash
+#
+#   $ ruff check pysphinxdoc
+###
+name: "PythonLinter[ruff]"
+
+on:
+  push:
+    branches:
+      - "master"
+      - "main"
+      - "dev"
+  pull_request:
+    branches:
+      - "*"
+  workflow_dispatch:
+
+jobs:
+  ruff:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: [3.12]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install ruff
+        pip install --progress-bar off .
+    - name: Lint with Ruff
+      run: |
+        ruff check pysphinxdoc

.github/workflows/pep8.yml

@@ -1,12 +1,24 @@
-name: "PEP8"
+---
+# Workflow to check code format.
+#
+# To run this check locally from the repository folder:
+#
+# .. code-block:: bash
+#
+#   $ pycodestyle pysphinxdoc --ignore="E121,E123,E126,E226,E24,E704,E402,E731,E722,E741,W503,W504,W605,E305"
+###
+name: "PythonLinter[pycodestyle]"
 
 on:
   push:
     branches:
       - "master"
+      - "main"
+      - "dev"
   pull_request:
     branches:
       - "*"
+  workflow_dispatch:
 
 jobs:
   build:

.github/workflows/release-documentation.yml

@@ -0,0 +1,92 @@
+# Workflow to build doc, and deploy it using the version as a subdomain.
+#
+# To run this check locally from the `doc` folder:
+#
+# .. code-block:: bash
+#
+#   $ sphinxdoc -v 2 -p $MODULE_DIR -n $MODULE_NAME -o $MODULE_DIR/doc
+#   $ cd $MODULE_DIR/doc
+#   $ make html-strict
+###
+name: "DocumentationRelease"
+
+on:
+  workflow_dispatch:
+
+env:
+  MIN_PYTHON_VERSION: "3.12"
+
+jobs:
+
+  build_and_deploy:
+
+    runs-on: "ubuntu-latest"
+    strategy:
+      fail-fast: false
+
+    permissions:
+      contents: write
+
+    steps:
+    - name: Extract branch name
+      id: extract-branch
+      shell: bash
+      run: echo "BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT
+    - name: Checkout repository
+      uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ env.MIN_PYTHON_VERSION }}
+        cache: "pip"
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools
+        pip install --progress-bar off .
+    - name: Install apt packages
+      uses: awalsh128/cache-apt-pkgs-action@latest
+      with:
+        packages: dvipng texlive-latex-base texlive-latex-extra build-essential
+        version: 1.0
+    - name: Install documentation resources
+      run: |
+        DIR=$(pwd)
+        which python
+        sphinxdoc -v 2 -p $DIR -n pysphinxdoc -o $DIR/doc
+    - name: Compute documentation
+      run: |
+        DIR=$(pwd)
+        cd $DIR/doc
+        echo "Documentation folder: $DIR/doc"
+        make html-strict
+        cd $DIR
+    - name: Upload documentation as an artifact
+      uses: actions/upload-artifact@v4
+      env:
+        BRANCH: ${{ steps.extract-branch.outputs.BRANCH }}
+      with: 
+        name: doc-${{ env.BRANCH }}
+        retention-days: 1
+        path: |
+            doc/_build/html
+    - name: Extract module version
+      id: extract-version
+      shell: python
+      run: |
+        import os
+        import pysphinxdoc
+        with open(os.environ["GITHUB_OUTPUT"], "a") as of:
+          of.write(f"VERSION={pysphinxdoc.__version__}")
+    - name: Deploy
+      env:
+        BRANCH: ${{ steps.extract-branch.outputs.BRANCH }}
+        ENV: ${{ steps.extract-version.outputs.VERSION }}
+      if: env.BRANCH == 'master' || env.BRANCH == 'main'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: doc/_build/html
+        destination_dir: ./${{ env.VERSION }}

AUTHORS.rst

@@ -0,0 +1,18 @@
+.. -*- mode: rst -*-
+
+.. _core_devs:
+
+Core developers
+...............
+
+The core developers are:
+
+* Antoine Grigis
+
+
+Other contributors
+..................
+
+Some other past or present contributors are:
+
+* Oneeb Nasir