Vie de document confortable avec Sphinx + Drone + S3

La maintenance des documents est un défi éternel pour toute organisation. Cette fois, je présenterai le mécanisme de maintenance des documents internes que je souhaite conserver, qui est adopté dans Server Platform Team.

Qu'est-ce que Sphinx

Sphinx est un outil de génération de documents basé sur Python. Vous pouvez créer un document composé de HTML en utilisant le langage de balisage reStructuredText comme source. Vous pouvez rechercher Markdown ou AsciiDoc avec un plug-in, ou vous pouvez intégrer PlantUML.

Hébergement de documents Sphinx

Si vous souhaitez publier un document créé avec Sphinx, il est facile d'utiliser readthedocs.org. Si vous utilisez Github ou Gitlab, vous pouvez utiliser github.io ou Gitlab Pages. Nous utilisons AWS pour placer les fichiers générés par Sphinx sur S3, les héberger dans le bon domaine et limiter la portée de la divulgation avec les bonnes politiques.

Qu'est-ce qu'un drone

Drone est un outil CI basé sur Go. C'est un outil simple qui exécute une tâche dans un conteneur Docker déclenché par un événement dans le référentiel Git. Nous construisons et exploitons un serveur Drone en interne pour le développement.

Aperçu

Avec le flux suivant, en utilisant le push to Gitlab comme opportunité, créez le document Sphinx avec Drone et téléchargez-le sur S3.

par ça

• Les rédacteurs de documents peuvent écrire en langage de balisage
• Ceux qui veulent lire le document peuvent le lire dans un format structuré en HTML
• Les notifications Slack peuvent détecter lorsqu'un document est mis à jour
• Comme il est géré par Git, vous pouvez naturellement voir les différences et les journaux.

Est réalisé.

Choses à faire

AWS

1. Préparez un compartiment S3 pour le téléchargement
2. Obtenez la clé d'accès AWS et le secret d'accès AWS pour le compartiment S3
3. Hébergez le compartiment S3 dans le domaine approprié

Drone

1. Activez la coopération avec Gitlab
2. Enregistrez la clé d'accès S3 AWS et le secret d'accès AWS

Gitlab

1. Définissez l'URL et le jeton du drone

2. Écrivez .drone.yml dans le référentiel de la documentation Sphinx comme suit ([atlassian / pipelines-awscli](https://hub.docker.com/r/atlassian] pour l'image docker pour le téléchargement S3 Utilisez / pipelines-awscli))

   pipeline:
     build:
       image: python:3
       commands:
         - pip install Sphinx
         - make html
       when:
         event: push
         branch: master
   
   push-contents:
       image: atlassian/pipelines-awscli
       secrets:
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
       commands:
         - aws s3 sync --delete _build/html/ s3://<Nom du compartiment S3 créé>/
       when:
         event: push
         branch: master
   

3. Le document Sphinx sera maintenant terminé lorsqu'il sera poussé vers le master.

à la fin

La documentation est souvent une tâche ardue, mais elle peut aussi être inévitable. Cependant, s'il existe un mécanisme qui facilite l'écriture de beaux documents, mystérieusement, l'écriture progressera. En tant qu'ingénieur d'application côté serveur, pourquoi ne pas avoir une vie documentaire confortable dans notre entreprise? https://jobs.qiita.com/postings/238