docStatic

Une solution de documentation composable basée sur Docusaurus 3 et TinaCMS (y compris la gestion des balises), OpenAPI, Mermaid graphiques, Lunr intégration de la recherche et Raw Loader pour les extraits de code.

Le projet a été créé en créant un nouveau site Docusaurus v3 avec le OpenAPI plugin de Palo Alto Networks et en fusionnant Tinasaurus pour créer une configuration fonctionnelle.

Note : La recherche Lunr n'est disponible qu'en production.

Cette démo inclut l'utilisation d'extraits (partiels), d'extraits de code et de variables (sur la page de test). Elle inclut un exemple de flux de travail pour la collection Docs dans Tina :

Draft → In Review → In Translation → Published

Il vous permet de définir le drapeau Unlisted et un drapeau Translation Approved à partir de Tina.

Développement local

# cloner le dépôt
git clone git@github.com:aowendev/docstatic.git

# cd dans le dossier du projet
$ yarn

# Démarrer le serveur de développement local
$ yarn dev

Cela permet d'installer les dépendances et d'ouvrir le site web dans votre navigateur.

Visitez le CMS à l'adresse http://localhost:3000/admin pour commencer à éditer.

Structure des dossiers

├── /apis: Schémas OpenAPI
├── /blog: articles de blog
├── /docs: documents pour les utilisateurs
│   └── /wiki: wiki
├── /i18n: la traduction
├── /reuse: contenu réutilisable
│   ├── /code: extraits de code
│   ├── /snippets: extraits de texte
│   └── /taxonomy: étiquettes de taxonomie
└── /static: contenu statique
    ├─── /img: images
    └─── /reuse: contenu réutilisable
         ├── /glossaryTerms: termes de glossaire traduisibles
         └── /variableSets: ensembles de variables traduisibles

Générer des documents OpenAPI

Pour générer tous les documents OpenAPI, exécutez la commande suivante à partir du dossier racine de votre projet :

yarn gen-api-docs all

Ceci génère les documents de l'API pour tous les fichiers de la spécification OpenAPI (OAS) référencés dans votre configuration docusaurus-plugin-openapi-docs.

Vous pouvez aussi générer des documents OpenAPI pour un seul chemin ou OAS en spécifiant l'unique id :

yarn gen-api-docs <id>

Exemple :

yarn gen-api-docs petstore

Cela ne génère que les documents de l'API relatifs à petstore.

Si vous avez plusieurs versions de la même API, gen-api-docs ne génère que la plus récente. Pour générer toutes les versions, utilisez le drapeau --all-versions.

Exemple :

yarn gen-api-docs all --all-versions

Ceci génère les documents de l'API pour toutes les versions de tous les fichiers de la spécification OpenAPI (OAS) référencés dans votre configuration docusaurus-plugin-openapi-docs.

Nettoyage des documents de l'API

Pour nettoyer/supprimer tous les documents API, exécutez cette commande à partir du dossier racine de votre projet :

yarn clean-api-docs all

Vous pouvez également supprimer un ensemble particulier de documents de l'API en spécifiant l'id unique de l'instance de spécification souhaitée.

yarn clean-api-docs <id>

Exemple :

yarn clean-api-docs petstore

Ceci supprime tous les documents de l'API relatifs à burgers.

Si vous avez plusieurs versions de la même API, clean-api-docs ne nettoie que la plus récente. Pour nettoyer toutes les versions, utilisez le drapeau --all-versions.

Exemple :

yarn clean-api-docs all --all-versions

Ceci nettoie les docs API pour toutes les versions de tous les fichiers de spécification OpenAPI (OAS) référencés dans votre configuration docusaurus-plugin-openapi-docs.

Versioning OpenAPI docs

Pour générer tous les documents OpenAPI versionnés, exécutez cette commande depuis le dossier racine de votre projet :

yarn gen-api-docs:version <id>:all

Exemple :

yarn gen-api-docs:version petstore:all

Ceci génère les documents de l'API pour tous les fichiers de la spécification OpenAPI (OAS) référencés dans votre configuration versions et génère également un fichier versions.json.

Remplacez all par un identifiant de version spécifique pour générer/nettoyer une version spécifique. Générer pour all ou un identifiant de version spécifique met automatiquement à jour le fichier versions.json.

Construire

$ yarn build

Cette commande génère du contenu statique dans le dossier build et peut être servie par n'importe quel service d'hébergement de contenu statique. Par exemple, cette commande permet de générer un contenu statique dans le dossier build :

npm run serve

Déploiement

Pour déployer en production et supporter l'édition sur votre site web (à votre-entreprise.github.io/baseurl/admin), suivez les étapes de TinaCMS pour déployer vers les pages GitHub.