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

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

Recommended Posts

Vie de document confortable avec Sphinx + Drone + S3
Vie de document confortable avec Docutils et Ruby
Génération automatique de documents à partir de docstring avec sphinx
Programmes Python de document HTML avec Sphinx
Téléchargeur S3 avec boto
Comment sortir un document au format pdf avec Sphinx