Restructuration du dépôt Git

État actuel du dépôt

Le dépôt agautheron/RT_Models contient actuellement des fichiers RST à la racine, des dossiers thématiques physique (bloch/, diffusion/, etc.) et les fichiers de configuration Sphinx (conf.py, _ext/, _static/).

RT_Models/                    ← état actuel
├── conf.py
├── index.rst
├── transfert_radiatif.rst
├── solutions.rst
├── bloch/
├── diffusion/
├── quantification/
├── spatial_encoding/
├── spectroscopy/
├── _ext/
├── _static/
└── .github/workflows/

Problèmes identifiés :

• Les fichiers RST de contenu sont mélangés aux fichiers de configuration Sphinx à la racine.

• Il n’y a pas de séparation claire entre la documentation et les sources Python/MATLAB.

• Le nouveau chapitre Verilog/FPGA n’a pas de place naturelle.

Structure recommandée

RT_Models/                          ← racine du dépôt
│
├── conf.py                         ← config Sphinx (reste à la racine)
├── index.rst                       ← toctree principal
├── requirements.txt
├── Makefile
│
├── _ext/                           ← extensions Sphinx personnalisées
├── _static/                        ← CSS, images globales
│
├── transfert_radiatif/             ← chapitre 1 (physique RT)
│   ├── index.rst                   ← toctree du chapitre
│   ├── introduction.rst
│   ├── equation_transfert.rst
│   ├── moments.rst
│   └── figures/
│
├── modeles_numeriques/             ← chapitre 2 (bloch, diffusion…)
│   ├── index.rst
│   ├── bloch.rst
│   ├── diffusion.rst
│   └── ...
│
├── verilog_fpga/                   ← chapitre 3 (ce cours) ← NOUVEAU
│   ├── index.rst
│   ├── 01_introduction.rst
│   ├── 02_syntaxe.rst
│   ├── 03_logique_combinatoire.rst
│   ├── 04_logique_sequentielle.rst
│   ├── 05_xadc_analogique.rst
│   ├── 06_comparateur.rst
│   ├── 07_edge_detector.rst
│   ├── 08_diviseur.rst
│   ├── 09_top_module.rst
│   ├── 10_contraintes_xdc.rst
│   ├── 11_testbench.rst
│   └── figures/
│
├── src/                            ← sources exécutables (séparés des docs)
│   ├── python/
│   │   ├── simulator.py
│   │   └── style.py
│   ├── matlab/
│   │   └── Simulator.m
│   └── verilog/                    ← fichiers .v du chapitre FPGA
│       ├── xadc_wrapper.v
│       ├── comparator.v
│       ├── edge_detector.v
│       ├── freq_divider.v
│       ├── top_nexys4.v
│       ├── constraints/
│       │   └── nexys4_ddr.xdc
│       └── sim/
│           └── tb_top.v
│
└── .github/
    └── workflows/
        └── sphinx.yml              ← CI/CD pour ReadTheDocs / GitHub Pages

Migration pas à pas

Voici la séquence de commandes Git pour migrer sans perdre l’historique :

# 1. Créer les nouveaux dossiers
mkdir -p verilog_fpga/figures
mkdir -p src/verilog/constraints src/verilog/sim

# 2. Déplacer les fichiers RST existants dans leur dossier
git mv transfert_radiatif.rst transfert_radiatif/
git mv solutions.rst           transfert_radiatif/

# 3. Ajouter les nouveaux fichiers RST du chapitre Verilog
git add verilog_fpga/

# 4. Ajouter les sources Verilog dans src/
git add src/verilog/

# 5. Mettre à jour index.rst (utiliser la version fournie)
git add index.rst

# 6. Commit atomique
git commit -m "docs: restructure repo + add verilog_fpga chapter"

Important

Faire la migration dans un seul commit pour conserver la cohérence de l’historique et faciliter un éventuel git bisect.

Workflow GitHub Actions recommandé

Ce workflow reconstruit la documentation Sphinx et la déploie sur GitHub Pages à chaque push sur main :

.github/workflows/sphinx.yml

name: Build & Deploy Sphinx docs

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

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Build HTML docs
        run: make html

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_build/html

Fichier requirements.txt minimal

sphinx>=7.0
furo
sphinxcontrib-katex
sphinx-inline-tabs
sphinx-math-dollar
sphinx-togglebutton

Conventions de nommage des fichiers RST

Contexte	Convention adoptée	Exemple
Section principale d’un chapitre	NN_nom_court.rst (préfixe numérique)	07_edge_detector.rst
Index de chapitre	index.rst dans le sous-dossier	verilog_fpga/index.rst
Figures	nom_module_description.svg ou .png	edge_detector_chronogram.svg
Sources exécutables	Dossier src/ séparé, même nom que le module	src/verilog/edge_detector.v

Cette séparation entre rst (documentation) et src/verilog (code exécutable) permet de faire tourner Vivado directement sur src/ sans mélanger les fichiers de documentation.