PRD v3.3 SPAN SG – MkDocs avec checklist officielle

Version 3.3 Date 30 septembre 2025 Owner Alexandra Validateur Alexandra (alexandra.guiderdoni@gmail.com) Sponsor Stéphane (Chef mission numérique SNUM-SG, validation conceptuelle)

1. objectif

Créer un framework simple et modulaire pour le SPAN SG permettant

édition décentralisée par service, 2) agrégation automatique SG, 3) versioning, 4) export HTML/PDF, 5) scoring automatique sur la checklist DINUM (33 critères).
Principe directeur: simple, fonctionnel, efficace.

2. architecture simplifiée

2.1 structure pyramidale

Niveau 1 : SPAN SG (Global)
  ├─ Niveau 2 : Modules Services (SNUM, SIRCOM, SRH, SIEP, SAFI, BGS)
  │   └─ Niveau 3 : Détails par service
  └─ (Futur) extensions autres directions

2.2 structure des fichiers

span-sg/
├─ mkdocs.yml
├─ mkdocs-pdf.yml
├─ docker-compose.yml
├─ .github/workflows/build.yml
├─ docs/
│  ├─ index.md
│  ├─ synthese.md                # généré par script
│  ├─ modules/
│  │  ├─ _template.md
│  │  ├─ snum.md
│  │  ├─ sircom.md
│  │  ├─ srh.md
│  │  ├─ siep.md
│  │  ├─ safi.md
│  │  └─ bgs.md
│  └─ assets/custom.css
├─ scripts/calculate_scores.py
├─ exports/                      # non versionné
└─ site/                         # non versionné

3. configuration technique minimale

3.1 mkdocs configuration

# mkdocs.yml
site_name: SPAN SG
site_url: https://[a-definir].github.io/span-sg/
repo_url: https://github.com/[organisation]/span-sg
strict: true

theme:
  name: material
  language: fr
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate

plugins:
  - search:
      lang: fr
  - pdf-export:
      combined: true
      combined_output_path: exports/span-sg.pdf

nav:
  - Accueil: index.md
  - Synthèse: synthese.md
  - Modules Services:
    - SNUM: modules/snum.md
    - SIRCOM: modules/sircom.md
    - SRH: modules/srh.md
    - SIEP: modules/siep.md
    - SAFI: modules/safi.md
    - BGS: modules/bgs.md

markdown_extensions:
  - tables
  - toc:
      permalink: true

3.2 scoring des 33 critères

Principe: seules les cases marquées  sont comptées.
Le script échoue si un module contient un nombre de points différent de 33 (ou 0 si non renseigné).

#!/usr/bin/env python3
# scripts/calculate_scores.py
import re
from pathlib import Path
from datetime import datetime

CHECK_TAG = "CHECKLIST"
FENCE_RE = re.compile(r"```.*?```", re.S)
BOX_RE = re.compile(r"- \[(x|X| )\].*?<!--\\s*%s\\s*-->" % CHECK_TAG)

def load_text(p: Path) -> str:
    return FENCE_RE.sub("", p.read_text(encoding="utf-8"))

def score_module(p: Path):
    boxes = BOX_RE.findall(load_text(p))
    total = len(boxes)
    checked = sum(1 for b in boxes if b.lower() == "x")
    return checked, total

def generate_summary():
    modules_dir = Path("docs/modules")
    rows = [
        "# Tableau de bord SPAN SG",
        f"*Mis à jour le {datetime.now():%d/%m/%Y}*",
        "",
        "| Service | Score | Statut |",
        "|---------|-------|--------|",
    ]
    total_checked = 0
    total_items = 0
    errors = []

    for module in sorted(modules_dir.glob("*.md")):
        if module.name.startswith("_"):
            continue
        checked, total = score_module(module)
        if total not in (0, 33):
            errors.append(f"{module.name}: {total} points tagués <!-- {CHECK_TAG} --> (attendu 33 ou 0)")
        pct = round((checked / total) * 100, 1) if total else 0.0
        status = "✓ Conforme" if pct >= 75 else "En cours" if total else "Non renseigné"
        rows.append(f"| {module.stem.upper()} | {checked}/{total} ({pct}%) | {status} |")
        total_checked += checked
        total_items += total

    global_pct = round((total_checked / total_items) * 100, 1) if total_items else 0.0
    rows.append(f"| **TOTAL** | **{total_checked}/{total_items} ({global_pct}%)** | **Global** |")

    Path("docs/synthese.md").write_text("\\n".join(rows) + "\\n", encoding="utf-8")

    if errors:
        print("Erreurs de périmètre:")
        for e in errors:
            print(" -", e)
        return 2
    return 0

if __name__ == "__main__":
    raise SystemExit(generate_summary())

3.3 export PDF simplifié

Objectif Générer un PDF d'archive à chaque build pour documentation et releases.

Stratégie

Plugin principal: mkdocs-pdf-export-plugin
Méthode manuelle de secours: impression navigateur sur page « Synthèse »

Configuration PDF

# mkdocs-pdf.yml
site_name: SPAN SG
theme:
  name: material
plugins:
  - pdf-export:
      combined: true
      combined_output_path: exports/span-sg.pdf

4. workflow git simplifié

Branches
main production
draft preview privée
feature/ modifications par service

Process

service crée feature/update-[service]
modifie son module
PR vers draft
revue Bertrand/Alex
preview privée (voir 5.1)
PR draft vers main
présentation Stéphane + validation Chef SNUM
tag version

Gestion d’urgence
hotfix/ vers main pour corrections critiques, revue rapide.

Checklist de revue PR
33 critères DINUM présents, pas de cases orphelines, front-matter, dates cohérentes, liens valides, pas d’identifiants en clair, synthèse CI OK, intitulés propres.

5. authentification et accès

5.1 accès preview privé (option A figée)

Principe
GitHub Pages sert la prévisualisation de draft; l’accès est limité aux membres de l’organisation GitHub.

Quand l’utiliser
Lorsque toute l’équipe dispose d’un compte GitHub dans l’organisation.

Mise en place en 3 lignes

Activer GitHub Pages sur le dépôt (ou un dépôt dédié gh-pages) au niveau de l’organisation
Restreindre l’accès aux membres de l’organisation dans les paramètres Pages
Déployer depuis la CI vers la branche gh-pages via peaceiris/actions-gh-pages (destination draft/)

5.2 production

Déploiement main vers GitHub Pages (branche gh-pages, racine). Accès selon politique de l’organisation.

6. conformité et transparence

6.1 blocs légaux à intégrer

Bloc pour docs/index.md

## Déclarations d’accessibilité

Pour chaque service
- Nom du service
- URL de la déclaration d’accessibilité
- Date de mise à jour de la déclaration
- Méthode d’évaluation (audit interne/tiers, date)
- Contact accessibilité

## Mentions de charge disproportionnée

Si applicable, pour chaque service
- Fonctionnalité/section concernée
- Justification documentée (technique/financière/organisationnelle)
- Alternative proposée (canal/équivalent)
- Échéance de réévaluation

Bloc pour chaque module (en pied de page)

## publication et conformité

- Déclaration d’accessibilité: [URL]
- Charge disproportionnée: [Oui/Non]. Si Oui, préciser
  - Élément: [...]
  - Justification: [...]
  - Alternative: [...]
  - Réévaluation: [date]

7. guide contributeur (1 page)

Option A interface GitHub (débutants)

aller sur github.com/[org]/span-sg
docs/modules/[service].md
icône crayon Edit
cocher uniquement les lignes 
Commit changes
PR vers draft

Option B Git local (avancés)
clone, branche, éditer, docker compose up, commit, push, PR.

8. maintenance minimale

Hebdomadaire revue PR + synthèse CI.
Mensuelle merge draft→main + tag version + export PDF d’archive.
Trimestrielle mise à jour dépendances et revue globale.

9. release en 5 étapes

But
Tag, traçabilité, PDF d’archive attaché à la release.

Étapes

préparer la version
Mettre à jour la version/date en tête de PRD et vérifier la synthèse CI.

changelog bref
Créer/mettre à jour CHANGELOG.md

## vX.Y.Z – AAAA-MM-JJ
- Ajout …
- Correction …
- Note d’impact …

taguer

git tag -a vX.Y.Z -m "Release SPAN SG vX.Y.Z"
git push origin vX.Y.Z

construire et récupérer artefacts
CI publie site/ et exports/span-sg.pdf.
créer la release GitHub
Titre SPAN SG vX.Y.Z
Joindre exports/span-sg.pdf
Lier le changelog et la décision GO/NO-GO.

Critères d’acceptation
Release publiée avec tag, changelog ≤ 3 puces, PDF joint.

10. décisions et hypothèses mvp

Décisions figées

Preview privée: GitHub Pages restreint aux membres de l'organisation (Option A)
PDF d'archive: plugin mkdocs-pdf-export-plugin + méthode manuelle (impression navigateur)
Modèles légaux: blocs standardisés dans index.md et dans chaque module

Hors périmètre MVP
dashboard temps réel, API, notifications, signature électronique, multi-tenant.

11. plan de mise en œuvre

Semaine 1 setup [x] repo GitHub privé [x] docker local [x] mkdocs base + strict [x] template 31  [x] script scoring testé [x] import module SIRCOM

Semaine 2 automatisation [ ] GitHub Actions ordre corrigé [ ] export PDF automatique [ ] preview privée (Option A) [ ] doc contributeur 1 page [ ] qualité code (tests + linting) [ ] tests E2E et CI local

Semaine 3 onboarding services
[ ] modules vides + front-matter
[ ] formation Git basique 2 h
[ ] premiers contenus

Semaine 4 production [ ] review contenus [ ] présentation Stéphane + validation Chef SNUM [ ] tag v1.0.0 [ ] publication

12. contacts

Rôle	Nom	GitHub
Owner	Alexandra	@alexandra
Validateur	Bertrand	@bertrand
Validateur	Alex	@alex
Sponsor	Stéphane (Chef mission numérique SNUM-SG)	-
Validation finale prod	Chef SNUM	-

13. décision go/no-go

PRD v3.3 avec checklist officielle, 30 septembre 2025
Principe: simple, fonctionnel, efficace, conforme

annexes « prêts à coller »

A. scripts/calculate_scores.py

(identique au bloc 3.2 ci-dessus, fourni pour collage direct dans le repo)

B. .github/workflows/build.yml

name: Build SPAN

on:
  push:
    branches: [main, draft]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mkdocs-material
          pip install mkdocs-pdf-export-plugin

      - name: Calculate SPAN scores
        run: python scripts/calculate_scores.py

      - name: Build site
        run: mkdocs build

      - name: Generate PDF
        run: mkdocs build --config-file mkdocs-pdf.yml

      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: span-site
          path: |
            site/
            exports/

  deploy_draft:
    if: github.ref == 'refs/heads/draft'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy draft to GitHub Pages (org-only)
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          publish_branch: gh-pages
          destination_dir: draft
          force_orphan: true

  deploy_main:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy production to GitHub Pages (org-only)
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          publish_branch: gh-pages
          force_orphan: true

C. docs/index.md – blocs légaux

## Déclarations d’accessibilité

Pour chaque service
- Nom du service
- URL de la déclaration d’accessibilité
- Date de mise à jour de la déclaration
- Méthode d’évaluation (audit interne/tiers, date)
- Contact accessibilité

## Mentions de charge disproportionnée

Si applicable, pour chaque service
- Fonctionnalité/section concernée
- Justification documentée (technique/financière/organisationnelle)
- Alternative proposée (canal/équivalent)
- Échéance de réévaluation

E. docs/modules/_template.md – squelette 33 critères balisés

---
service: [SERVICE]
referent: "[Prénom Nom]"
updated: "2025-09-30"
---

# SPAN [SERVICE] - Schéma Pluriannuel d'accessibilité numérique

**Période** 2025-2027  
**Score global** [X/33] questions validées ([XX] %)  
**Dernière mise à jour** [DATE]

## Checklist de conformité (33 critères)

- [ ] Critère #01 <!-- CHECKLIST -->
- [ ] Critère #02 <!-- CHECKLIST -->
- [ ] Critère #03 <!-- CHECKLIST -->
- [ ] Critère #04 <!-- CHECKLIST -->
- [ ] Critère #05 <!-- CHECKLIST -->
- [ ] Critère #06 <!-- CHECKLIST -->
- [ ] Critère #07 <!-- CHECKLIST -->
- [ ] Critère #08 <!-- CHECKLIST -->
- [ ] Critère #09 <!-- CHECKLIST -->
- [ ] Critère #10 <!-- CHECKLIST -->
- [ ] Critère #11 <!-- CHECKLIST -->
- [ ] Critère #12 <!-- CHECKLIST -->
- [ ] Critère #13 <!-- CHECKLIST -->
- [ ] Critère #14 <!-- CHECKLIST -->
- [ ] Critère #15 <!-- CHECKLIST -->
- [ ] Critère #16 <!-- CHECKLIST -->
- [ ] Critère #17 <!-- CHECKLIST -->
- [ ] Critère #18 <!-- CHECKLIST -->
- [ ] Critère #19 <!-- CHECKLIST -->
- [ ] Critère #20 <!-- CHECKLIST -->
- [ ] Critère #21 <!-- CHECKLIST -->
- [ ] Critère #22 <!-- CHECKLIST -->
- [ ] Critère #23 <!-- CHECKLIST -->
- [ ] Critère #24 <!-- CHECKLIST -->
- [ ] Critère #25 <!-- CHECKLIST -->
- [ ] Critère #26 <!-- CHECKLIST -->
- [ ] Critère #27 <!-- CHECKLIST -->
- [ ] Critère #28 <!-- CHECKLIST -->
- [ ] Critère #29 <!-- CHECKLIST -->
- [ ] Critère #30 <!-- CHECKLIST -->
- [ ] Critère #31 <!-- CHECKLIST -->
- [ ] Critère #32 <!-- CHECKLIST -->
- [ ] Critère #33 <!-- CHECKLIST -->

## périmètre du service

| Type | Total | Audités | Conformes | Score |
|------|-------|---------|-----------|-------|
| Sites web | | | | % |
| Intranets | | | | % |
| Applications | | | | % |

## plan d'actions prioritaires 2025

| Action | Échéance | Responsable | Budget | Statut |
|--------|----------|-------------|--------|--------|
| | T1 2025 | | € | |
| | T2 2025 | | € | |

## publication et conformité

- Déclaration d’accessibilité: [URL]
- Charge disproportionnée: [Oui/Non]. Si Oui, préciser
  - Élément: [...]
  - Justification: [...]
  - Alternative: [...]
  - Réévaluation: [date]

---
*Dernière mise à jour [date]*

clarification périmètre v1

Seuls les 6 modules suivants sont inclus en v1: SNUM, SIRCOM, SRH, SIEP, SAFI, BGS. Les autres directions sont planifiées en phase 2+.

options non retenues (mvp)

HTML avec includes: non retenu (CDC impose MkDocs/GitHub Pages)
PHP avec includes: non retenu (CDC impose MkDocs/GitHub Pages)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PRD v3.3 SPAN SG – MkDocs avec checklist officielle

1. objectif

2. architecture simplifiée

2.1 structure pyramidale

2.2 structure des fichiers

3. configuration technique minimale

3.1 mkdocs configuration

3.2 scoring des 33 critères

3.3 export PDF simplifié

4. workflow git simplifié

5. authentification et accès

5.1 accès preview privé (option A figée)

5.2 production

6. conformité et transparence

6.1 blocs légaux à intégrer

7. guide contributeur (1 page)

8. maintenance minimale

9. release en 5 étapes

10. décisions et hypothèses mvp

11. plan de mise en œuvre

12. contacts

13. décision go/no-go

annexes « prêts à coller »

A. scripts/calculate_scores.py

B. .github/workflows/build.yml

C. docs/index.md – blocs légaux

E. docs/modules/_template.md – squelette 33 critères balisés

clarification périmètre v1

options non retenues (mvp)

FilesExpand file tree

PRD-v3.3.md

Latest commit

History

PRD-v3.3.md

File metadata and controls

PRD v3.3 SPAN SG – MkDocs avec checklist officielle

1. objectif

2. architecture simplifiée

2.1 structure pyramidale

2.2 structure des fichiers

3. configuration technique minimale

3.1 mkdocs configuration

3.2 scoring des 33 critères

3.3 export PDF simplifié

4. workflow git simplifié

5. authentification et accès

5.1 accès preview privé (option A figée)

5.2 production

6. conformité et transparence

6.1 blocs légaux à intégrer

7. guide contributeur (1 page)

8. maintenance minimale

9. release en 5 étapes

10. décisions et hypothèses mvp

11. plan de mise en œuvre

12. contacts

13. décision go/no-go

annexes « prêts à coller »

A. scripts/calculate_scores.py

B. .github/workflows/build.yml

C. docs/index.md – blocs légaux

E. docs/modules/_template.md – squelette 33 critères balisés

clarification périmètre v1

options non retenues (mvp)