Configurer le dépôt

9 min

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 et paramétrer correctement votre dépôt afin qu’Archbee puisse y récupérer le contenu et l’organiser adéquatement 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 (si vous utilisez multipath) comme ce fichier .yaml, alors nous l’utilisons pour organiser le contenu.

Portez une attention particulière au fichier .yaml ici si vous souhaitez configurer le dossier à partir duquel le contenu markdown est généré (ou une hiérarchie d’arborescence de documents de synthèse).

Créer le 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 vos dépôts. Assurez-vous que le fichier reste à cet emplacement 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 chacun d’eux. 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 les docs (peut être remplacée 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 des 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 fantômes
publishSpace : booléen, à définir sur vrai si vous souhaitez publier l’espace vers 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 le 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. Il peut vous aider à organiser votre contenu efficacement.

Voici 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 Markdown de l’éditeur pour utiliser ces raccourcis.

Ajouter plusieurs référentiels

Suivez ces étapes simples pour ajouter plusieurs référentiels et les synchroniser avec Archbee :

Accédez à votre compte GitHub connecté avec Archbee, puis accédez à la page Paramètres.

Dans la barre latérale de gauche, recherchez Applications.

Page des applications GitHub

Cliquez sur le bouton Configure et, lorsque la nouvelle page s’ouvre, accordez l’accès à :

Tous les référentiels (cela signifie que vous pouvez sélectionner n’importe quel référentiel depuis votre compte Archbee)
Seulement des référentiels sélectionnés (sélectionnez tout nouveau référentiel que vous souhaitez synchroniser avec Archbee)
Cliquez sur Save

Sélectionner les référentiels

Retournez à votre compte Archbee.

Dans le panneau de navigation de gauche, créez un nouvel Espace -> choisissez Écrire dans GitHub et sélectionnez les référentiels nouvellement ajoutés.

Importer des fichiers Open Api

Vous pouvez en fait 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: ""

Have a question?

Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.

To ask a question or participate in discussions, you'll need to authenticate first.