Aller au contenu

🚀 Guide de Démarrage MkDocs pour Jnane

Installation Rapide (5 minutes)

Prérequis

  • Python 3.8+ installé
  • pip (gestionnaire de packages Python)

Étape 1 : Installer les Dépendances

# Depuis la racine du projet jnane.lang
pip install -r requirements.txt

Installation réussie si vous voyez : 

Successfully installed mkdocs-1.5.3 mkdocs-material-9.5.0 ...

Étape 2 : Lancer le Serveur de Développement

mkdocs serve

Résultat attendu : 

INFO    - Building documentation...
INFO    - [macros] - Macros plugin initialized
INFO    - Documentation built in 2.50 seconds
INFO    - [16:30:00] Serving on http://127.0.0.1:8000/

Étape 3 : Ouvrir dans le Navigateur

Ouvrir : http://127.0.0.1:8000

🎉 Votre documentation est en ligne !

📂 Structure de la Documentation

jnane.lang/
├── mkdocs.yml              # Configuration MkDocs
├── requirements.txt        # Dépendances Python
│
├── docs/                   # Contenu MkDocs
│   ├── index.md           # Page d'accueil
│   ├── macros.py          # Macros personnalisées (GitHub issues, etc.)
│   ├── stylesheets/
│   │   └── extra.css      # Styles personnalisés
│   ├── javascripts/
│   │   └── mathjax.js     # Configuration MathJax
│   ├── guide/             # Guides utilisateur
│   └── scripts/           # Docs des scripts
│       └── github-cli-guide.md
│
├── project/                # Intégré dans la doc
│   ├── spec/
│   │   └── features/      # 127 features FEAT-XXX
│   └── docs/              # Documentation projet
│
├── src/main/
│   ├── sample/            # 93 exemples .jn
│   └── doc/               # Documentation technique
│
└── site/                  # Généré par mkdocs build (ignoré par Git)

🎨 Fonctionnalités Activées

  • Onglets : Organisation par grandes sections
  • Recherche : Full-text avec suggestions (FR + EN)
  • Breadcrumbs : Fil d'Ariane
  • TOC : Table des matières intégrée
  • Bouton "Top" : Retour en haut de page

✅ GitHub Integration

Macros Disponibles

Dans vos fichiers .md, utilisez :

<!-- Lien vers issue GitHub -->
[#123](https://github.com/gregoirerichard/jnane.lang/issues/123)
Résultat : [#123](https://github.com/gregoirerichard/jnane.lang/issues/123)

<!-- Badge de statut -->
![Statut](https://img.shields.io/badge/statut-Implémenté-success)
Résultat : ![Statut](https://img.shields.io/badge/statut-Implémenté-success)

<!-- Badge de maturité -->
![Maturité](https://img.shields.io/badge/maturit%C3%A9-4.2/5.0-brightgreen)
Résultat : ![Maturité](https://img.shields.io/badge/maturité-4.2/5.0-brightgreen)

<!-- Lien vers spec FEAT-XXX -->
[FEAT-009](/project/spec/features/03-syntax/07-named-arguments-FEAT-009.md)
Résultat : [FEAT-009](/project/spec/features/.../FEAT-009.md)

<!-- Lien vers sample -->
[`namedArguments.jn`](https://github.com/gregoirerichard/jnane.lang/blob/main/src/main/sample/namedArguments.jn)
Résultat : [`namedArguments.jn`](https://github.com/.../namedArguments.jn)

<!-- Créer nouvelle issue -->
[Créer une issue](https://github.com/gregoirerichard/jnane.lang/issues/new?title=Bug Report&labels=bug)
Résultat : [Créer une issue](https://github.com/.../issues/new?title=Bug+Report&labels=bug)

GitHub CLI dans la Documentation

Créer une issue :


```bash
gh issue create --title 'My Issue' --label feature

### ✅ Extensions Markdown

- **Admonitions** : Notes, warnings, tips
- **Tabs** : Contenu à onglets
- **Code highlighting** : Coloration syntaxique
- **Mermaid** : Diagrammes
- **Task lists** : Checkboxes interactives
- **MathJax** : Formules mathématiques
- **Emoji** : Support complet :rocket:

### ✅ Thème Material

- **Mode sombre/clair** : Toggle automatique
- **Couleurs** : Indigo primary, Deep Purple accent
- **Responsive** : Mobile-friendly
- **Fonts** : Roboto + Roboto Mono

---

## 📝 Ajouter du Contenu

### Créer une Nouvelle Page

```powershell
# Créer un fichier dans docs/
New-Item docs/guide/nouveau-guide.md

Contenu exemple :

# Mon Nouveau Guide

## Introduction

Contenu ici...

[#123](https://github.com/gregoirerichard/jnane.lang/issues/123)

## Exemple de Code

```jnane
main = print(message: "Hello!")

Note

Information

Ceci est une note importante.

### Ajouter à la Navigation

Éditer `mkdocs.yml` :

```yaml
nav:
  - Guide de Démarrage:
    - Introduction: guide/introduction.md
    - Nouveau Guide: guide/nouveau-guide.md  # ← Ajouter ici

Preview en Temps Réel

Avec mkdocs serve actif, les changements sont automatiquement rechargés !

🔍 Recherche

La recherche est activée automatiquement :

  • Langues : Français + Anglais
  • Suggestions : Affichées pendant la frappe
  • Highlight : Résultats surlignés
  • Partage : URL de recherche partageable

Utilisation : Cliquer sur 🔍 ou / pour chercher.

🎨 Personnalisation

Modifier les Couleurs

Éditer mkdocs.yml :

theme:
  palette:
    primary: indigo      # Changer ici (blue, teal, etc.)
    accent: deep purple  # Changer ici

Couleurs disponibles : red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

Ajouter du CSS Personnalisé

Éditer docs/stylesheets/extra.css :

/* Vos styles ici */
.ma-classe-custom {
  color: red;
}

Ajouter du JavaScript

Créer docs/javascripts/custom.js :

console.log("Custom JS loaded!");

Puis ajouter dans mkdocs.yml :

extra_javascript:
  - javascripts/custom.js

🚀 Build et Déploiement

Build Local

mkdocs build

Résultat : Dossier site/ avec HTML statique.

Preview du Build

mkdocs build
cd site
python -m http.server 8080

Ouvrir : http://localhost:8080

Déploiement GitHub Pages

# Build et push vers gh-pages branch
mkdocs gh-deploy

# Avec message custom
mkdocs gh-deploy --message "Deploy documentation v1.0"

URL publique : https://gregoirerichard.github.io/jnane.lang

⚠️ Note : Sur repo privé, GitHub Pages nécessite GitHub Pro.

Déploiement Manuel

# Build
mkdocs build

# Copier site/ vers votre serveur web
# Exemple avec rsync :
rsync -avz site/ user@server:/var/www/docs/

🐛 Dépannage

Erreur : "mkdocs: command not found"

# Vérifier installation
pip list | Select-String mkdocs

# Réinstaller si nécessaire
pip install --upgrade mkdocs mkdocs-material

Erreur : "No module named 'mkdocs_macros'"

pip install mkdocs-macros-plugin

Port 8000 déjà utilisé

# Utiliser un autre port
mkdocs serve --dev-addr 127.0.0.1:8080

Rechargement ne fonctionne pas

# Mode strict
mkdocs serve --strict

# Nettoyer et rebuild
Remove-Item -Recurse -Force site
mkdocs serve

Macros ne fonctionnent pas

Vérifier mkdocs.yml :

plugins:
  - macros:
      module_name: docs/macros  # Chemin correct ?

📚 Exemples d'Usage

Exemple 1 : Feature avec Issue GitHub

# FEAT-009 : Arguments Nommés

![Statut](https://img.shields.io/badge/statut-Implémenté-success) ![Maturité](https://img.shields.io/badge/maturit%C3%A9-3.0/5.0-yellow)

**GitHub Issue** : [#42](https://github.com/gregoirerichard/jnane.lang/issues/42)

## Description

Les arguments nommés permettent...

## Exemple

```jnane
result = math:add(a: 5, b: 3)

Sample

Voir namedArguments.jn 

### Exemple 2 : Guide avec Tabs

```markdown
# Installation

=== "Windows"

    ```powershell
    winget install jnane
    ```

=== "macOS"

    ```bash
    brew install jnane
    ```

=== "Linux"

    ```bash
    sudo apt install jnane
    ```

Exemple 3 : Admonitions

!!! note "Information"
    Ceci est une note.

!!! warning "Attention"
    Soyez prudent !

!!! tip "Astuce"
    Utilisez `gh` pour automatiser.

!!! danger "Danger"
    Ne pas exécuter en production.

🔗 Intégration GitHub CLI

La documentation inclut un guide complet GitHub CLI :

Accès : /scripts/github-cli-guide

Contenu : - Installation gh - Authentification - Gestion issues - Automatisation - Intégration avec Jnane

📊 Statistiques

La page d'accueil affiche automatiquement :

  • 127 features documentées
  • 93 samples exécutables
  • 56 docs techniques
  • 200+ tests

Ces stats peuvent être mises à jour dans docs/index.md.

🎯 Prochaines Étapes

  1. Lancer : mkdocs serve
  2. Explorer : http://127.0.0.1:8000
  3. Personnaliser : Modifier docs/index.md
  4. Ajouter contenu : Créer pages dans docs/
  5. Build : mkdocs build quand prêt
  6. Déployer : mkdocs gh-deploy (si repo public)

📖 Ressources

Documentation MkDocs

Jnane Specific

❓ Questions Fréquentes

Q : Puis-je utiliser MkDocs sur un repo privé ?
R : Oui ! La doc fonctionne en local. Pour GitHub Pages sur repo privé, il faut GitHub Pro.

Q : Comment ajouter un logo ?
R : Créer docs/assets/logo.svg et configurer dans mkdocs.yml : 

theme:
  logo: assets/logo.svg

Q : Les macros fonctionnent-elles dans tous les fichiers ?
R : Oui, dans tous les .md sous docs/, project/, src/main/doc/.

Q : Puis-je intégrer mon code Java ?
R : Oui, avec pymdownx.snippets (exemple si le fichier existe)

Besoin d'aide ? Créer une issue : Créer une issue

Dernière mise à jour : 26 octobre 2025