[PYTHON] Komfortables Dokumentenleben mit Sphinx + Drone + S3

Die Pflege von Dokumenten ist eine ewige Herausforderung für jedes Unternehmen. Dieses Mal werden wir den Wartungsmechanismus für interne Dokumente vorstellen, den Sie beibehalten möchten, der in Server Platform Team übernommen wird.

Was ist Sphinx?

Sphinx ist ein Python-basiertes Tool zur Dokumentenerstellung. Sie können ein aus HTML bestehendes Dokument aus der Auszeichnungssprache reStructuredText erstellen. Sie können Markdown oder AsciiDoc mit einem Plug-In beschaffen oder PlantUML einbetten.

Hosting von Sphinx-Dokumenten

Wenn Sie ein mit Sphinx erstelltes Dokument veröffentlichen möchten, können Sie einfach readthedocs.org verwenden. Wenn Sie Github oder Gitlab verwenden, möchten Sie möglicherweise github.io oder Gitlab Pages verwenden. Wir verwenden AWS, um von Sphinx generierte Dateien in S3 abzulegen, sie in der richtigen Domäne zu hosten und den Umfang der Offenlegung mit den richtigen Richtlinien zu begrenzen.

Was ist Drohne?

Drone ist ein Go-basiertes CI-Tool. Es ist ein einfaches Tool, das einen Job in einem Docker-Container ausführt, wenn ein Ereignis im Git-Repository ausgelöst wird. Wir bauen und betreiben einen eigenen Drohnen-Server für die Entwicklung.

Überblick

Befolgen Sie die nachstehenden Anweisungen, um das Sphinx-Dokument mit Drone zu erstellen und in S3 hochzuladen, ausgelöst durch den Push an Gitlab.

dadurch

• Dokumentschreiber können in Auszeichnungssprache schreiben
• Wer das Dokument lesen möchte, kann es in einem strukturierten Format in HTML lesen
• Slack-Benachrichtigungen können erkennen, wann ein Dokument aktualisiert wird
• Da es von Git verwaltet wird, können Sie natürlich diff und log sehen.

Wurde verwirklicht.

Dinge die zu tun sind

AWS

1. Bereiten Sie einen S3-Bucket zum Hochladen vor
2. Holen Sie sich den AWS-Zugriffsschlüssel und das AWS-Zugriffsgeheimnis für den S3-Bucket
3. Hosten Sie den S3-Bucket in der entsprechenden Domäne

Drone

1. Aktivieren Sie die Zusammenarbeit mit Gitlab
2. Registrieren Sie den S3 AWS-Zugriffsschlüssel und das AWS-Zugriffsgeheimnis

Gitlab

1. Stellen Sie die URL und das Token der Drohne ein

2. Schreiben Sie .drone.yml wie folgt in das Repository für die Sphinx-Dokumentation ([atlassian / pipelines-awscli](https://hub.docker.com/r/atlassian] für das Docker-Image für den S3-Upload) (Use / 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://<S3-Bucket-Name erstellt>/
       when:
         event: push
         branch: master
   

3. Jetzt ist das Sphinx-Dokument fertig, wenn es an den Master gesendet wird.

schließlich

Das Dokumentieren ist oft eine entmutigende Aufgabe, kann aber auch unvermeidlich sein. Wenn es jedoch einen Mechanismus gibt, der es einfach macht, schöne Dokumente zu schreiben, wird das Schreiben auf mysteriöse Weise voranschreiten. Warum haben Sie als serverseitiger Anwendungstechniker nicht ein angenehmes Dokumentenleben in unserem Unternehmen? https://jobs.qiita.com/postings/238