Merge pull request #1118 from mlco2/issue-1108

docs: restructure documentation using Diataxis framework

Author: benoit-cty

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,7 +20,7 @@ What types of changes does your code introduce? Put an `x` in all the boxes that
 
 ## AI Usage Disclosure
 
-Please refer to [docs/contributing/AI_POLICY.md](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/AI_POLICY.md) for detailed guidelines on how to disclose AI usage in your PR. Accurately completing this section is mandatory.
+Please refer to [docs/how-to/ai-policy.md](https://docs.codecarbon.io/how-to/ai_policy/) for detailed guidelines on how to disclose AI usage in your PR. Accurately completing this section is mandatory.
 
 - [ ] 🟥 AI-vibecoded: You cannot explain the logic. Car analogy : the car drive by itself, you are outside it and just tell it where to go.
 - [ ] 🟠 AI-generated: Car analogy : the car drive by itself, you are inside and give instructions.
@@ -32,7 +32,7 @@ Go over all the following points, and put an `x` in all the boxes that apply.
 - [ ] My code follows the code style of this project.
 - [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
-- [ ] I have read the **[docs/contributing/CONTRIBUTING.md](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/CONTRIBUTING.md)** document.
+- [ ] I have read the **[docs/how-to/contributing.md](https://docs.codecarbon.io/how-to/contributing/)** document.
 - [ ] I have added tests to cover my changes.
 - [ ] All new and existing tests passed.
 

.github/copilot-instructions.md

@@ -1 +1 @@
-../docs/contributing/agents-instructions.md
+../docs/how-to/agent-instructions.md

.github/workflows/build-docs.yml

@@ -9,12 +9,12 @@ on:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "scripts/check_docs_links.py"
+      - ".github/workflows/build-docs.yml"
   pull_request:
     branches: [master]
-    paths:
-      - "docs/**"
-      - "mkdocs.yml"
-      - ".github/workflows/build-docs.yml"
 
 jobs:
   build:
@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version: "latest"
 
@@ -36,10 +36,11 @@ jobs:
       - name: Build docs
         run: |
           set -euo pipefail
-          # Run zensical and capture output, fail if command exits non-zero
           uv run zensical build -f mkdocs.yml --clean 2>&1 | tee docs_build.log
-          # If output contains common error indicators, fail the step.
           if grep -Ei "\b(error|failed|traceback|exception)\b" docs_build.log >/dev/null; then
             echo "Documentation build produced errors; failing workflow."
             exit 1
           fi
+
+      - name: Check documentation links (site/)
+        run: uv run python scripts/check_docs_links.py site

.github/workflows/build-server.yml

@@ -15,9 +15,9 @@ jobs:
   build_server:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Install uv
-      uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+      uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
       with:
         version: "latest"
     - name: Set up Python
@@ -52,9 +52,9 @@ jobs:
           # Maps tcp port 5432 on service container to the host
           - 5480:5432
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Install uv
-      uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+      uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
       with:
         version: "latest"
     - name: Set up Python

.github/workflows/build-ui.yml

@@ -21,7 +21,7 @@ jobs:
     build-ui:
         runs-on: ubuntu-22.04
         steps:
-            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+            - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
             - name: Use Node.js
               uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
               with:

.github/workflows/codeql.yml

@@ -51,7 +51,7 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - "scripts/deploy-docs.sh"
       - "codecarbon/_version.py"
       - "pyproject.toml"
+      - "scripts/check_docs_links.py"
   release:
     types: [published]
 
@@ -36,7 +37,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version: "latest"
 
@@ -60,6 +61,9 @@ jobs:
       - name: Build docs
         run: uv run zensical build -f mkdocs.yml --clean
 
+      - name: Check documentation links
+        run: uv run python scripts/check_docs_links.py site
+
       - name: Deploy to GitHub Pages
         env:
           GITHUB_REPOSITORY: ${{ github.repository }}

.github/workflows/deploy.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout code
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0 # Same as git fetch --unshallow
         clean: true    # Remove any untracked files or modifications

.github/workflows/package-validation-reusable.yml

@@ -11,11 +11,12 @@ env:
 
 jobs:
   build-package:
+    if: github.event_name == 'release' || github.ref == 'refs/heads/master' || (github.event_name == 'pull_request' && github.base_ref == 'master')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Install uv
-        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version: "latest"
       - name: Set up Python
@@ -25,7 +26,7 @@ jobs:
       - name: Build pip package
         run: uv build
       - name: Archive Pypi artifacts
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: pypi_dist
           path: dist
@@ -34,40 +35,37 @@ jobs:
     runs-on: ubuntu-24.04
     needs: [build-package]
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           sparse-checkout: |
             tests/
             pytest.ini
+            docs/
+            pyproject.toml
+            uv.lock
           sparse-checkout-cone-mode: false
       - name: Install uv
-        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version: "latest"
       - name: Set up Python
         run: uv python install ${{ env.MAIN_PYTHON_VERSION }}
       - name: Download built package
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: pypi_dist
           path: dist
-      - name: Create clean virtual environment
+      - name: Sync dev dependencies from lockfile and install wheel
         run: |
-          uv venv .venv --python ${{ env.MAIN_PYTHON_VERSION }}
-          echo "VIRTUAL_ENV=$PWD/.venv" >> $GITHUB_ENV
-          echo "$PWD/.venv/bin" >> $GITHUB_PATH
-      - name: Install package from wheel (without source)
-        run: |
-          # Install the wheel and test dependencies without the source code
-          uv pip install dist/*.whl
-          uv pip install pytest pytest-mock requests-mock responses pandas logfire
+          uv sync --python ${{ env.MAIN_PYTHON_VERSION }} --frozen --no-install-project --group dev
+          uv pip install --python .venv/bin/python dist/*.whl
       - name: Test package integrity
         run: |
-          # Run the package integrity tests to verify all data files are included
-          uv run python -m pytest tests/test_package_integrity.py -v
-          CODECARBON_ALLOW_MULTIPLE_RUNS=True pytest --ignore=tests/test_viz_data.py -vv -m 'not integ_test' tests/
+          .venv/bin/python -m pytest tests/test_package_integrity.py -v
+          CODECARBON_ALLOW_MULTIPLE_RUNS=True .venv/bin/python -m pytest \
+            --ignore=tests/test_viz_data.py \
+            -vv -m 'not integ_test' tests/
       - name: Test CLI functionality
         run: |
-          # Test that the CLI is functional
-          codecarbon --help
-          python -c "from codecarbon import EmissionsTracker; print('Package import successful')"
+          .venv/bin/codecarbon --help
+          .venv/bin/python -c "from codecarbon import EmissionsTracker; print('Package import successful')"

.github/workflows/pre-commit.yml

@@ -12,7 +12,7 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
     - name: set PY
       run: echo "PY=$(python -c 'import hashlib, sys;print(hashlib.sha256(sys.version.encode()+sys.executable.encode()).hexdigest())')" >> $GITHUB_ENV