Ceci est un guide pour contribuer à la documentation officielle de l’API Discourse.
Niveau d’utilisateur requis : Développeur
Accès à la console requis
Souhaitez-vous contribuer à la documentation officielle de l’API sur https://docs.discourse.org ? Ce guide vous expliquera étape par étape comment procéder.
Résumé
Cette documentation vous guidera à travers les étapes suivantes :
- Configuration des prérequis.
- Clonage du dépôt de documentation de l’API Discourse.
- Modification des fichiers de documentation de l’API.
- Visualisation de vos modifications localement.
- Création d’une pull request.
Prérequis
Vous devez disposer d’une installation de développement de Discourse. Si vous n’en avez pas, suivez le guide adapté à votre environnement dans ces sujets.
Clonage du dépôt de documentation de l’API Discourse
En supposant que votre installation de développement de Discourse se trouve dans votre répertoire personnel ~/, procédez comme suit pour cloner le dépôt :
-
Depuis votre répertoire personnel, clonez le dépôt à l’adresse https://github.com/discourse/discourse_api_docs :
git clone https://github.com/discourse/discourse_api_docs -
Vous devriez maintenant avoir les dossiers
discourseetdiscourse_api_docscôte à côte :~/discourse/ ~/discourse_api_docs/
Modification des fichiers de documentation de l’API
Vous devez modifier la documentation directement depuis ~/discourse/spec/requests/api/.
- Voir le dossier sur GitHub : discourse/spec/requests/api at main · discourse/discourse · GitHub
La documentation de l’API des plugins peut également être contribué via des fichiers de spécification situés dans plugins/*/spec/requests/api/.
Après avoir modifié les fichiers de documentation, exécutez la commande suivante depuis ~/discourse/ :
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
La documentation sera générée à l’aide de rswag et copiée dans ~/discourse_api_docs/.
Ensuite, convertissez le fichier YAML en JSON depuis ~/discourse_api_docs/ :
npm install
node tojson.js
Visualisation de vos modifications localement
Pour visualiser votre documentation mise à jour, suivez ces étapes :
-
Depuis
~/discourse_api_docs/, exécutez :npm install node server.js -
Accédez à http://localhost:3001 pour voir la documentation mise à jour.
Création d’une pull request
Une fois que vous avez vérifié que tout semble correct, créez une pull request à partir du dépôt discourse/discourse (pas du dépôt Discourse API Docs).
Le dépôt discourse_api_docs est mis à jour automatiquement chaque jour via un flux de travail GitHub Actions qui régénère la spécification OpenAPI à partir des dernières spécifications du noyau de Discourse. Vous n’avez pas besoin de soumettre une PR distincte à ce dépôt.
Problèmes courants et solutions
Signaler des erreurs dans la documentation de l’API Discourse
Si vous rencontrez des problèmes ou des erreurs dans la documentation de l’API Discourse, veuillez les signaler sur le forum Discourse Meta - vous pouvez suivre le guide de rapport de bug pour vous aider à le faire efficacement.