feat: add docs.yml workflow to handle all CI tasks related to documen…

…tation

.github/workflows/links.yml → .github/workflows/docs.yml

@@ -1,31 +1,75 @@
-name: Check URLs with Lychee and Sphinx
+name: Documentation
 
 on:
+  workflow_dispatch:
+  pull_requests:
   push:
     branches:
       - main
       - develop
-  pull_request:
   schedule:
-    # Run everyday at 3 am UTC
+    # Run every day at 3 am UTC
     - cron: "0 3 * * *"
 
+env:
+  PYBAMM_DISABLE_TELEMETRY: "true"
+  FORCE_COLOR: 3
+  PYBAMM_IDAKLU_EXPR_CASADI: ON
+  PYBAMM_IDAKLU_EXPR_IREE: ON
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  linkCheckerLychee:
+  docs:
     runs-on: ubuntu-latest
     steps:
+      # Checkout repository code
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      # Install Linux system dependencies
+      - name: Install Linux system dependencies
+        uses: awalsh128/cache-apt-pkgs-action@a6c3917cc929dd0345bfb2d3feaf9101823370ad # v1.4.2
+        with:
+          packages: graphviz pandoc
+          execute_install_scripts: true
 
-      # Cache Lychee results to avoid hitting rate limits
-      - name: Restore lychee cache
-        uses: actions/cache@v4
+      # Install TeXLive for Linux
+      - name: Install TeXLive for Linux
+        run: |
+          sudo apt-get update
+          sudo apt-get install texlive-latex-extra dvipng
+
+      # Set up Python
+      - name: Set up Python
+        uses: actions/setup-python@v4
         with:
-          path: .lycheecache
-          key: cache-lychee-${{ github.sha }}
-          restore-keys: cache-lychee-
+          python-version: "3.11"
+          cache: 'pip'
 
-      # Check URLs with Lychee
-      - uses: actions/checkout@v4
+      # Upgrade pip and install dependencies for PyBaMM
+      - name: Install PyBaMM with [docs,all]
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs,all]
+
+      # Run doctests for Python 3.11
+      - name: Run doctests
+        run: python -m nox -s doctests
+
+      # Build the docs (HTML)
+      - name: Build docs (HTML)
+        run: sphinx-build -b html docs/ docs/_build/html
+
+      # Check links in the documentation with Sphinx
+      - name: Run Sphinx linkcheck
+        run: sphinx-build -b linkcheck docs/ docs/_build/linkcheck
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      # Run Lychee URL checker in parallel (No redundant checkout)
       - name: Lychee URL checker
         uses: lycheeverse/[email protected]
         with:
@@ -57,29 +101,3 @@ jobs:
           format: markdown
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  linkcheckerSphinx:
-    runs-on: ubuntu-latest
-    needs: linkCheckerLychee
-
-    steps:
-      # Checkout repository code
-      - uses: actions/checkout@v4
-
-      # Install Python and dependencies for Sphinx
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.9"
-
-      - name: Install PyBaMM with [docs,all]
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e .[docs,all]
-
-      # Run Sphinx's linkcheck builder
-      - name: Run Sphinx linkcheck
-        run: |
-          sphinx-build -b linkcheck . _build/linkcheck || exit 1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test_on_push.yml

@@ -131,50 +131,50 @@ jobs:
         run: python -m nox -s integration
 
   # Skips IDAKLU module compilation for speedups, which is already tested in other jobs.
-  run_doctests:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-    name: Doctests (ubuntu-latest / Python 3.11)
-
-    steps:
-      - name: Check out PyBaMM repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: 0
-
-      - name: Install Linux system dependencies
-        uses: awalsh128/cache-apt-pkgs-action@a6c3917cc929dd0345bfb2d3feaf9101823370ad # v1.4.2
-        with:
-          packages: graphviz pandoc
-          execute_install_scripts: true
-
-      # dot -c is for registering graphviz fonts and plugins
-      - name: Install TeXLive for Linux
-        run: |
-          sudo apt-get update
-          sudo dot -c
-          sudo apt-get install texlive-latex-extra dvipng
-
-      - name: Set up Python
-        id: setup-python
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: 3.11
-          cache: 'pip'
-
-      - name: Set up uv
-        run: python -m pip install uv
-
-      - name: Install nox
-        run: python -m uv pip install nox[uv]
-
-      - name: Install docs dependencies and run doctests for GNU/Linux
-        run: python -m nox -s doctests
-
-      - name: Check if the documentation can be built for GNU/Linux
-        run: python -m nox -s docs
-
+  # run_doctests:
+  #   runs-on: ubuntu-latest
+  #   strategy:
+  #     fail-fast: false
+  #   name: Doctests (ubuntu-latest / Python 3.11)
+  #
+  #   steps:
+  #     - name: Check out PyBaMM repository
+  #       uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+  #       with:
+  #         fetch-depth: 0
+  #
+  #     - name: Install Linux system dependencies
+  #       uses: awalsh128/cache-apt-pkgs-action@a6c3917cc929dd0345bfb2d3feaf9101823370ad # v1.4.2
+  #       with:
+  #         packages: graphviz pandoc
+  #         execute_install_scripts: true
+  #
+  #     # dot -c is for registering graphviz fonts and plugins
+  #     - name: Install TeXLive for Linux
+  #       run: |
+  #         sudo apt-get update
+  #         sudo dot -c
+  #         sudo apt-get install texlive-latex-extra dvipng
+  #
+  #     - name: Set up Python
+  #       id: setup-python
+  #       uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+  #       with:
+  #         python-version: 3.11
+  #         cache: 'pip'
+  #
+  #     - name: Set up uv
+  #       run: python -m pip install uv
+  #
+  #     - name: Install nox
+  #       run: python -m uv pip install nox[uv]
+  #
+  #     - name: Install docs dependencies and run doctests for GNU/Linux
+  #       run: python -m nox -s doctests
+  #
+  #     - name: Check if the documentation can be built for GNU/Linux
+  #       run: python -m nox -s docs
+  #
   run_example_tests:
     runs-on: ubuntu-latest
     strategy: