Aller au contenu principal

Installation

Bienvenue ! Ce guide vous explique comment configurer DocStatic pour la première fois.

Si vous n'avez jamais utilisé GitHub ou docs-as-code auparavant, ne vous inquiétez pas : nous vous expliquerons ce dont vous avez besoin, pourquoi et où trouver plus de détails.

Prérequis​

Vous pouvez exécuter DocStatic localement (sur votre ordinateur) ou l'héberger dans le cloud.

Pour une configuration cloud simplifiée, créez des comptes gratuits auprès des services suivants :

  • GitHub — stocke votre contenu et suit les modifications
  • TinaCMS — permet l'édition via un navigateur
  • LanguageTool — fournit une vérification facultative de la grammaire et du style

Si vous prévoyez plutôt d'exécuter DocStatic localement (sur votre ordinateur), consultez la section Conditions requises pour le développement local.

Conditions requises pour le développement local​

Cette section ne s'applique que si vous prévoyez de travailler localement.

Vous aurez besoin d'un environnement de développement intégré (IDE) ou d'un éditeur de texte. Voici deux options open source :

Vous devrez également installer Node.js pour ses outils de compilation et Yarn pour la gestion des paquets.

Installer Node.js​

Vous devez installer Node.js version 18.0 ou supérieure.

Vérifiez si Node.js est déjà installé. Ouvrez un terminal (invite de commande ou application Terminal) et exécutez :

node -v

Si vous voyez un numéro de version commençant par v18 ou supérieur, vous êtes prêt à continuer.

Si Node.js n'est pas installé ou si vous disposez d'une version plus ancienne :

  1. Rendez-vous sur la page de téléchargement officielle de Node.js.
  2. Choisissez la version LTS (Long-Term Support) adaptée à votre système d'exploitation. Le programme d'installation inclut npm, le gestionnaire de paquets Node, dont vous aurez besoin dans les étapes suivantes. Pendant l'installation :* Conservez les options par défaut sélectionnées (celles-ci incluent les dépendances requises) * Une fois l'installation terminée, fermez et rouvrez votre terminal.
  3. (Facultatif) si vous travaillez sur différents projets qui nécessitent différentes versions de Node, installez nvm (Node Version Manager). Avec nvm, vous pouvez passer d'une version de Node à une autre sans perturber votre configuration.

Installer Yarn​

DocStatic utilise Yarn pour la gestion des paquets.

Vérifiez si Yarn est déjà installé. Ouvrez votre terminal ou votre invite de commande et tapez :

yarn -v

Si vous voyez un numéro de version, Yarn est déjà installé.

Si vous obtenez un message « commande introuvable » ou une erreur similaire, ouvrez un terminal (invite de commande ou application Terminal) et exécutez :

npm install -g yarn
Remarque

Sur macOS ou Linux, vous devrez peut-être préfixer la commande avec sudo pour accorder l'autorisation :

sudo npm install -g yarn
Remarque

Sous Windows, vous n'utilisez pas sudo. Il vous suffit d'ouvrir votre terminal en tant qu'administrateur et d'exécuter la commande.

Obtenir le référentiel DocStatic​

Le code source de DocStatic se trouve sur GitHub. Pour commencer, vous devez créer votre propre copie en :

  1. Créer une fourche du dépôt DocStatic La fourche crée une copie que vous pouvez utiliser pour travailler indépendamment sur votre propre projet.
  2. Créer un clone de votre fourche. Le clonage crée une copie associée à la fourche originale que vous avez créée. Cela peut être utile pour corriger des problèmes de schéma, s'ils surviennent ultérieurement.

Fourcher le dépôt DocStatic​

  1. Connectez-vous à votre compte GitHub.
  2. Rendez-vous sur https://github.com/aowendev/docstatic.
  3. Cliquez sur Fork (généralement en haut à droite).
  4. Laissez le nom du référentiel par défaut.
  5. Saisissez une description de votre projet.
  6. Assurez-vous que l'option Copier uniquement la branche principale est cochée.
  7. Cliquez sur Créer une fourche.

GitHub crée une nouvelle branche du référentiel dans votre compte GitHub.

Clonez votre fourche du référentiel DocStatic​

Pour créer un clone :

  1. Connectez-vous à votre compte GitHub.
  2. Accédez au référentiel de la fourche.
  3. Cliquez sur le référentiel pour l'ouvrir.
  4. Cliquez sur <> Code, puis copiez l'URL.
  5. Ouvrez votre terminal ou votre invite de commande et utilisez cd pour accéder à l'emplacement où vous souhaitez stocker le clone. Par exemple, cd Documents/Projets/.
  6. Entrez git clone suivi de l'URL de votre clone.
git clone https://github.com/acme-projects/docstatic.git

Installer les dépendances du projet​

Si vous comptez travailler localement, vous devez également installer les dépendances du projet. Utilisez cd pour naviguer jusqu'au dossier racine de votre dépôt DocStatic cloné ou forké et installez les paquets :

cd docstatic
yarn install

Yarn téléchargera tout ce qui est répertorié dans package.json. Cela peut prendre quelques minutes.

Structure du projet​

Après avoir forké ou cloné le dépôt, vous verrez divers fichiers dans votre dossier docstatic/. Ci-dessous, nous avons inclus certains des fichiers et dossiers de la structure du projet que vous devez connaître. Il ne s'agit pas d'une liste complète de tout ce qui se trouve dans le projet.

docstatic
├── apis
│   └── petstore.yaml
├── blog
│   └── hybrid.mdx
├── config
│   ├── docusaurus
│   │   └── index.json
│   ├── homepage
│   │   └── index.json
│   └── sidebar
│       └── index.json
│
├── docs
│   └── introduction.mdx
├── i18n
│   └── fr
├── reuse
│   ├── code
│   │   └── example.xml
│   ├── conditions
│   │   └── index.json
│   ├── glossaryTerms
│   │   └── index.json
│   ├── snippets
│   │   └── example.mdx
│   ├── taxonomy
│   │   └── index.json
│   ├── variableSets
│   │   └── index.json
│   ├── code-files.json
│   └── snippets-files.json
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── example-page.mdx
│       ├── index.js
│       └── index.module.css
├── static
│   └── img
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock

Présentation de la structure du projet​

  • /apis/ - Fichiers YAML OpenAPI.
  • /blog/ - Fichiers MDX du blog.
  • /config/ - Fichiers JSON utilisés par TinaCMS pour configurer DocStatic.
  • /docs/ - Fichiers MDX de la documentation.
  • /i18n/ - Fichiers de traduction.
  • /reuse/ - Contenu réutilisable.
  • /src/ - Fichiers non liés à la documentation, tels que des pages ou des composants React personnalisés.
    • /src/pages - Tous les fichiers JSX/TSX/MDX de ce répertoire sont convertis en pages web.
  • /static/ - Dossier statique. Tout le contenu de ce dossier est copié à la racine du dossier de compilation final.
  • /docusaurus.config.ts - Fichier de configuration contenant la configuration du site.
  • /package.json - Un site web DocStatic est une application React. Vous pouvez installer et utiliser tous les paquets npm que vous souhaitez.
  • /sidebars.ts - Spécifie l'ordre des documents dans la barre latérale. Utilisez-le pour votre structure de « table des matières ».

Monorepos​

DocStatic permet d'utiliser un seul dépôt contenant à la fois le code du projet et la documentation du projet. Dans la terminologie Docusaurus, ce concept est appelé « monorepo ».

Pour plus d'informations, consultez Monorepos dans la documentation Docusaurus.

Prévisualiser les modifications​

Pour prévisualiser vos modifications au fur et à mesure que vous modifiez les fichiers, vous pouvez exécuter un serveur de développement local qui servira votre site web et reflétera les dernières modifications.

Ouvrez un terminal ou une invite de commande et entrez :

yarn dev

Par défaut, une fenêtre de navigateur s'ouvrira à l'adresse http://localhost:3000.

Compilation​

DocStatic utilise un générateur de site statique pour compiler le site web dans un dossier de contenu statique et le placer sur un serveur web où il peut être consulté. Pour compiler le site web, utilisez :

yarn build-local

Le contenu est généré dans le dossier /build, que vous pouvez copier vers n'importe quel service d'hébergement de fichiers statiques tel que GitHub pages, Netlify ou Vercel. Pour plus d'informations, consultez la section Déploiement dans la documentation Docusaurus.