Comfortable document life with Sphinx + Drone + S3

Document maintenance is an eternal challenge for any organization. This time, I will introduce the maintenance mechanism of internal documents that I want to persist, which is adopted in Server Platform Team.

What is Sphinx

Sphinx is a Python-based document generation tool. You can build a document composed of HTML using the markup language reStructuredText as a source. You can source Markdown or AsciiDoc by inserting a plugin, or you can embed PlantUML.

Hosting Sphinx documents

If you want to publish a document created with Sphinx, it's easy to use readthedocs.org. If you're using Github or Gitlab, you might want to use github.io or Gitlab Pages. We use AWS to put files generated by Sphinx on S3, host them to the appropriate domain, and limit the scope of disclosure with appropriate policies.

What is Drone

Drone is a Go-based CI tool. It's a simple tool that runs a job inside a Docker container triggered by an event in the Git repository. We build and operate an in-house Drone server for development.

Overview

With the following flow, using the push to Gitlab as an opportunity, build the Sphinx document with Drone and upload it to S3.

by this

• Document writers can write in markup language
• Those who want to read the document can read it in a structured format in HTML
• Slack notifications can detect when a document is updated
• Since it is managed by Git, you can naturally see diff and log.

Is realized.

things to do

AWS

1. Prepare an S3 bucket for uploading
2. Get the AWS access key and AWS access secret for your S3 bucket
3. Host your S3 bucket in a suitable domain

Drone

1. Turn on the cooperation with Gitlab
2. Register your S3 AWS access key and AWS access secret

Gitlab

1. Set Drone url and Token

2. Write .drone.yml in the repository for Sphinx documents as follows ([atlassian / pipelines-awscli](https://hub.docker.com/r/atlassian] for docker image for 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://<Created S3 bucket name>/
       when:
         event: push
         branch: master
   

3. Now the Sphinx document will be completed when it is pushed to master.

at the end

Documenting is often a daunting task, but it can also be unavoidable. However, if there is a mechanism that makes it easy to write beautiful documents, the brush will go on mysteriously. As a server-side application engineer, why not have a comfortable document life at our company? https://jobs.qiita.com/postings/238