Configurer le dépôt
Configurer le dépôt
En supposant que vous avez déjà terminé l’intégration, l’étape suivante consiste à configurer un dépôt.
Vous devez configurer correctement votre dépôt afin qu’Archbee puisse récupérer le contenu qui s’y trouve et l’organiser correctement de notre côté.
Vous pouvez forker ce dépôt.
Si le système trouve un fichier .archbee.yaml à la racine de votre dépôt ou dans d’autres dossiers (au cas où vous utilisez plusieurs chemins) comme ce fichier .yaml, alors nous l’utilisons pour organiser le contenu.
Faites très attention au fichier .yaml ici si vous souhaitez configurer le dossier à partir duquel le contenu markdown est rendu (ou une hiérarchie de documents de synthèse).
Créer un fichier .yaml
Créez un fichier .archbee.yaml avec la structure de variables suivante :
Vous devez placer le fichier dans le dossier racine de votre ou de vos dépôts. Assurez-vous que le fichier reste là puisqu’il s’agit de votre chemin par défaut pour les autres dossiers — si vous avez plusieurs dossiers, vous devez copier le fichier dans ces dossiers. Comment faire, demandez-vous? Consultez comment synchroniser plusieurs dossiers.
Que signifient toutes ces clés?
- root: ./docs : cette propriété définit où se trouve le répertoire contenant la documentation (peut être remplacé par docsPath: ./docs)
- structure :
- résumé: summary.md : reconstruit l’arborescence des documents dans le panneau de navigation de gauche dans Archbee. S’il n’y en a pas, nous considérons les dossiers comme les catégories et reproduisons la structure des fichiers à l’intérieur.
- actifs : actifs : le dossier assets est relatif à docsPath. Archbee téléversera tous les fichiers trouvés dans ce dossier (fichiers de code et images).
- shadowDocs : vous devez définir les fichiers/dossiers de code à inclure comme Documents de l'ombre
- publishSpace : booléen, définissez à vrai si vous souhaitez publier l’espace sur le portail de production après chaque commit
Exemple d’un fichier de configuration archbee.yaml :
root: doc-api
structure:
summary: summary.md
assets: assets
publishSpace: true
headerIncludes: |
<script>
document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script> Exemple d’un fichier de configuration archbee.json :
{
"root": "docfolderwithsummary",
"structure": {
"summary": "summary.md",
"assets": ".archbee/assets"
},
"customJS":"",
"customCSS":"* \n { font-family: \"Comic Sans MS\", cursive, sans-serif; }",
"footerTemplate": "",
"headerIncludes": ""
}Créer un fichier summary.md
Nous vous recommandons également de créer un fichier summary.md. Le fichier summary.md reconstruit l’arborescence des documents dans le panneau de navigation de gauche dans Archbee. Et il peut vous aider à organiser votre contenu proprement.
Voyez ci-dessous un exemple de fichier summary.md :
- [Introduction](1.md)
## Table of contents
- [Init](init.md)
- [Configure App](config.md)
- [Config Database](config-database.md)
- [Config Redis](config-redis.md)
- [Config Elastic Search](config-es.md)
- [Swagger](swagger-v2.json)
Utiliser la syntaxe Markdown avec GitHub
Certains blocs de contenu peuvent être rendus si vous utilisez une syntaxe spécifique.
Consultez les raccourcis Raccourcis Markdown de l’éditeur pour utiliser ces raccourcis.
Ajouter plusieurs dépôts
Suivez ces étapes simples pour ajouter plusieurs dépôts et les synchroniser avec Archbee :
Allez sur votre compte GitHub connecté avec Archbee, puis accédez à la page Paramètres.
Dans la barre latérale gauche, recherchez Applications.
Cliquez sur le bouton Configurer et lorsque la nouvelle page s’ouvre, accordez l’accès à :
- Tous les dépôts (cela signifie que vous pouvez sélectionner n’importe quel dépôt depuis votre compte Archbee)
- Seulement certains dépôts (sélectionnez tout nouveau dépôt que vous souhaitez synchroniser avec Archbee)
- Cliquez sur Enregistrer
Retournez à votre compte Archbee.
Depuis le panneau de navigation de gauche, créez un nouvel Espace -> choisissez Écrire dans GitHub et sélectionnez les dépôts récemment ajoutés.
Importer des fichiers Open Api
Vous pouvez importer des fichiers Open Api via GitHub. Cette fonctionnalité fonctionne exactement comme la fonctionnalité Importation d’OpenAPI / Swagger, y compris ses paramètres. Il y a 2 éléments importants à configurer :
- chemins vers les fichiers Open Api (.json, .yml, .yaml) à écrire dans le fichier de configuration summary.md
- paramètres à écrire dans le fichier de configuration principal sous docTreeOptions:
docsPath: ./myapp-docs
structure:
summary: toc.md
assets: assets
docTreeOptions:
openApiTryIt: false
showDownloadOpenApiFile: true
shouldCreateSchemaCategory: true
shouldCreateIntro: true
openApiLanguageExamples:
- value: python
label: py
- value: javascript
label: js
footerTemplate: ""
headerIncludes: ""