Documentation

• 1: Introduction
  • 1.1: Vue d’ensemble du projet
  • 1.2: Architecture
• 2: Premiers pas
  • 2.1: Prérequis
  • 2.2: Installation
• 3: Tutoriel
  • 3.1: Réaliser votre première modification
  • 3.2: Ajouter une page de documentation
• 4: Référence
  • 4.1: Configuration
  • 4.2: Référence des commandes

1 - Introduction

Commencez ici si vous découvrez le projet.

1.1 - Vue d’ensemble du projet

Remplacez cette page par l’explication la plus courte et utile de votre projet.

Le problème

Décrivez le problème avec les mots du lecteur. Évitez les détails d’implémentation tant que la valeur du projet n’est pas claire.

Le résultat

Expliquez ce qu’un utilisateur peut accomplir après avoir adopté le projet.

1.2 - Architecture

Documentez les quelques composants qu’un contributeur doit comprendre avant toute modification.

Carte du système

Limites

Indiquez ce que le projet ne prend volontairement pas en charge. Des limites claires évitent de promettre plus que le logiciel ne fournit.

2 - Premiers pas

Passez d’une machine propre à un résultat local fonctionnel.

2.1 - Prérequis

Gardez les prérequis courts, précis et vérifiables.

Outils

• Un système d’exploitation pris en charge.
• Git pour récupérer les sources.
• La version d’exécution requise par votre projet.

Vérifier

Donnez une commande par prérequis :

$ project --version
project 0.1.0

Remplacez cette commande fictive par la vôtre avant publication.

2.2 - Installation

Présentez d’abord le chemin d’installation pris en charge le plus court.

Installer

git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
./project start

Confirmer le résultat

Indiquez précisément à quoi ressemble la réussite : une URL à ouvrir, un message à voir ou une commande qui renvoie zéro.

3 - Tutoriel

Suivez une tâche de bout en bout plutôt qu’une suite de faits isolés.

3.1 - Réaliser votre première modification

Ce tutoriel modèle une tâche complète : préparer, modifier, vérifier et relire.

Partir d’un état connu

git status --short
git switch -c docs/first-change

Modifier une seule chose

Changez une chaîne visible ou une petite valeur de configuration. La première tâche doit rester assez ciblée pour que son résultat soit évident.

Vérifier

Exécutez le contrôle pertinent le plus petit, puis ouvrez la surface modifiée et inspectez-la vous-même.

3.2 - Ajouter une page de documentation

Dans OINK, l’arborescence du contenu devient la barre latérale. Un nouveau fichier Markdown crée une nouvelle page.

Créer le fichier

---
title: Nouvelle capacité
description: Ce que fait cette capacité.
weight: 30
---

Expliquez la capacité ici.

Enregistrez-le sous content/docs/reference/new-capability.md.

Ajouter les traductions

Créez new-capability.zh.md et new-capability.fr.md à côté. Gardez les identifiants explicites des titres alignés entre les langues.

Prévisualiser

Lancez hugo server, ouvrez la nouvelle page et utilisez le sélecteur de langue pour vérifier chaque traduction.

4 - Référence

Utilisez cette section lorsque vous savez déjà ce que vous cherchez.

4.1 - Configuration

Remplacez ce petit tableau par la véritable surface de configuration publique de votre projet.

Exemple

listen: 0.0.0.0:8080
log_level: debug
read_only: true

Documentez la validation et la priorité à côté des clés, pas dans un guide séparé et difficile à trouver.

4.2 - Référence des commandes

project start

Démarre le service local.

project start [--config FILE] [--listen ADDRESS]

project check

Valide la configuration sans démarrer le service. Le code de sortie 0 signifie valide ; tout autre code interdit le déploiement.

project check [--config FILE]

Remplacez ces exemples par les commandes issues de l’aide réelle de votre CLI.