|
|
||
|---|---|---|
| .forgejo/workflows | ||
| docs | ||
| README.md | ||
Mon Projet
Ce projet utilise Sphinx pour générer la documentation.
La documentation est écrite en Markdown grâce à MyST Parser.
Elle est générée automatiquement via Forgejo Actions.
Voici un exemple complet et minimal fonctionnel pour déployer une documentation Sphinx utilisant Markdown automatiquement avec Forgejo Actions.
1. Arborescence complète du dépôt
mon-projet/
│
├── README.md
│
├── docs/
│ ├── requirements.txt
│ ├── source/
│ │ ├── conf.py
│ │ ├── index.md
│ │ ├── usage.md
│ │ ├── _static/
│ │ └── _templates/
│ └── build/
│
└── .forgejo/
└── workflows/
└── deploy.yml
Chaque fichier est décrit ci-dessous.
2. README.md
Fichier d'information du dépôt.
# Mon Projet
Ce projet utilise **Sphinx** pour générer la documentation.
La documentation est écrite en **Markdown** grâce à MyST Parser.
Elle est générée automatiquement via **Forgejo Actions**.
3. docs/requirements.txt
Liste des dépendances nécessaires pour construire la documentation.
sphinx
myst-parser
furo
Description :
- sphinx : générateur de documentation
- myst-parser : support Markdown dans Sphinx
- furo : thème moderne pour la documentation
4. docs/source/conf.py
Fichier de configuration principal de Sphinx.
project = "Mon Projet"
author = "Auteur"
release = "0.1"
extensions = [
"myst_parser",
]
templates_path = ["_templates"]
exclude_patterns = []
html_theme = "furo"
html_static_path = ["_static"]
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
Description :
- configure le projet
- active l'extension Markdown
- définit le thème
- indique que les fichiers
.mdsont supportés
5. docs/source/index.md
Page principale de la documentation.
# Documentation
Bienvenue dans la documentation du projet.
## Sommaire
```{toctree}
:maxdepth: 2
:caption: Guide
usage
Description :
- page d'accueil
- contient un **toctree** qui structure les pages
---
# 6. docs/source/usage.md
Exemple de page de documentation.
```markdown
# Utilisation
## Installation
```bash
pip install mon-projet
Exemple
print("Hello world")
Description :
- montre comment utiliser le projet
- exemple simple
---
# 7. dossiers `_static` et `_templates`
Structure :
```text
_static/
_templates/
Utilisation :
_static: images, CSS, JS_templates: templates HTML personnalisés
Ces dossiers peuvent rester vides au début.
8. docs/build/
Dossier généré automatiquement par Sphinx.
Il contiendra :
docs/build/html/
avec les fichiers HTML générés.
Ce dossier ne doit pas être versionné.
9. Workflow Forgejo
.forgejo/workflows/deploy.yml
Ce fichier automatise :
- installation de Python
- installation de Sphinx
- build de la documentation
- déploiement sur la branche
gh-pages
name: deploy-docs
on:
push:
branches:
- main
- master
jobs:
deploy:
runs-on: docker
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Python
run: |
apt-get update
apt-get install -y python3 python3-pip make git
pip3 install --upgrade pip
- name: Install dependencies
run: |
pip3 install -r docs/requirements.txt
- name: Build documentation
run: |
sphinx-build -M html docs/source docs/build
- name: Deploy to gh-pages
run: |
git config user.name "forgejo-actions"
git config user.email "actions@forgejo"
git fetch origin gh-pages || true
git worktree add site gh-pages || git worktree add -b gh-pages site
rm -rf site/*
cp -r docs/build/html/* site/
cd site
git add .
git commit -m "Deploy documentation"
git push origin gh-pages
10. Fonctionnement global
Pipeline :
push sur main
↓
Forgejo Actions
↓
installation dépendances
↓
sphinx-build
↓
docs/build/html
↓
copie vers gh-pages
↓
site web généré
11. Test local
Pour tester avant le CI :
pip install -r docs/requirements.txt
sphinx-build -M html docs/source docs/build
Puis ouvrir :
docs/build/html/index.html
Si tu veux, je peux aussi te faire une version encore plus propre utilisée dans les vrais projets Sphinx :
- structure officielle recommandée
- auto-documentation du code Python
- preview local automatique
- déploiement Forgejo beaucoup plus simple (20 lignes au lieu de 60).