Sphinx＋Drone＋S3로 쾌적 문서 라이프

문서 유지 관리는 모든 조직에서 영원한 도전이라고 생각합니다.
이번에는 서버 플랫폼 팀 에서 도입하고 있는 영속화하고 싶은 사내용 문서의 유지 관리의 구조를 소개합니다.

Sphinx란?

스핑크스은 Python 기반 문서 생성 도구입니다.
마크업 언어인 reStructuredText를 소스로 사용하여 HTML로 구성된 문서를 빌드할 수 있습니다.
플러그인을 넣으면 Markdown 또는 AsciiDoc을 소스로 만들 수 있으며 PlantUML을 포함할 수도 있습니다.

Sphinx 문서 호스팅

Sphinx로 만든 문서를 공개하고 싶다면 희귀 d는 CS. 오 rg을 사용하기 쉽습니다.
Github 또는 Gitlab을 사용한다면 github.io 또는 Gitlab Pages를 사용하는 것이 좋습니다.
당사는 AWS를 활용하고 있으며 Sphinx에서 생성된 파일을 S3에 넣어 적절한 도메인에 호스팅하고 게시 범위를 적절한 정책으로 제한하는 등의 작업을 하고 있습니다.

Drone이란?

Drone은 Go 기반 CI 도구입니다.
Git 리포지토리에 대한 이벤트를 계기로 Docker 컨테이너 내에서 작업을 실행하는 간단한 도구입니다.
우리는 개발을 위해 내부에 Drone 서버를 구축하고 운영합니다.

개요

다음과 같은 흐름으로 Gitlab에 push를 계기로 Drone에서 Sphinx 문서를 빌드하고 S3에 업로드합니다.



이것으로

문서를 작성하는 사람은 마크 업 언어로 작성할 수 있습니다

문서를 읽고 싶은 사람은 HTML로 구조화 된 형식으로 읽을 수 있습니다

문서가 업데이트 된시기는 Slack 통지로 검지 가능

Git 관리되고 있으므로 diff 나 log 도 당연히 볼 수 있다

를 실현합니다.

할 일

AWS

업로드용 S3 버킷 준비

S3 버킷의 AWS 액세스 키 및 AWS 액세스 비밀 얻기

S3 버킷을 적절한 도메인에 호스팅

Drone

Gitlab과의 연동을 ON으로 설정

S3 AWS 액세스 키 및 AWS 액세스 비밀 등록

Gitlab

Drone url 및 Token 설정

Sphinx 문서용 리포지토리에서 .drone.yml

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 バケット名>/
    when:
      event: push
      branch: master

이상으로 마스터에 푸시 된 타이밍에 Sphinx 문서가 완성됩니다.

사이고에게

문서 작성은 종종 신경이 쓰이는 작업이지만, 피해서는 통과할 수 없는 것도 있습니다.
그러나 깨끗한 문서가 편하게 쓸 수 있는 구조가 있으면, 신기와 붓은 진행해 가는 것입니다.
여러분도 서버측 어플리케이션 엔지니어로서 당사에서 쾌적한 문서 라이프를 보내지 않겠습니까?
atlassian/pipelines-awscli