마스터 브랜치를 결합하는 동안 S3에 문서를 공개합니다.

10893 단어 GitHub CircleCI2.0 Sphinx Python

문제점으로 삼다

파이톤의 소스 코드에서 문서를 생성할 때 마스터가 업데이트한 후에 수동으로 문서를 생성하는데 설정하기가 번거롭고 업데이트를 잊어버릴 수도 있습니다.

해결 수단으로 삼다

GiitHub이 관리하는 창고에서 주요 지점이 통합될 때 GiitHub과Circle CI의integration을 통해 자동으로 문서를 구축하여 AWS 3에 놓는다.

사용할 도구, 서비스

다음과 같은 도구와 서비스를 사용합니다.

Sphinx: 문서 자동 생성

GiitHub: 버전 관리

Circle CI: 지속적인 통합(배송) 서비스

AWS CLI 도구: AWS 명령줄 인터페이스

전제로 삼다

Python3.사용하다

GiitHub의 창고와 Circle CI를 연결합니다.

방치지 S3의 구간이 이미 존재하고 적절한 권한을 가진 IAM을 설정했다.

프로젝트 구조

가공 파이썬 모듈'my tools'를 개발하는 임시 프로젝트를 사용합니다.

.
|____docs
|____my_tools
| |______init__.py
| |_____adder.py

docs에 Sphinx 관련 파일이 있습니다.
모듈 my구화기 adder.있다.
adder.py

# -*- coding: utf-8 -*-
"""加算に関するユーティリティーが入っているモジュールです."""


class Adder:
    """加算器."""

    def __init__(self) -> None:
        """初期化."""
        pass

    def add(self, x: int, y: int) -> int:
        """加算を実行するメソッド.

        :param x: 整数x
        :param y: 整数y
        :return: x と y の演算結果
        """
        return x + y

Sphinx

Sphinx 프로젝트 만들기

문서를 docs 아래에 생성하는 Sphinx 프로젝트를 만듭니다.
또 이 기사에는 스핑크스의 자세한 내용은 언급되지 않았다.최소한의 구성을 처리하다.

$ cd docs
$ sphinx-quickstart

몇 가지 질문을 표시합니다.최저한도를 미리 설정하다.

Project name

Author name(s)

Project version

autodoc

autodoc에 y 를 입력하십시오.
기타 Enter 키를 누를 때 기본 설정입니다.

구성 파일 편집 및 추가

index.rst

생성된 index입니다.rst의 toctree에서 이번 모듈 mytools를 추가합니다.
docs/my_tools

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   my_tools

my_tools.rst

이번에 추가된 모듈을 구축하기 위한 문서입니다.새 rst를 만듭니다.
docs/my_tools

my\_tools パッケージ
====================

..
  Submodules
  ----------

my\_tools\.adder モジュール
-------------------------------------------

.. automodule:: my_tools.adder
    :members:
    :undoc-members:
    :show-inheritance:

conf.py

코드 추가 및 편집
conf.py


import os
import sys

sys.path.insert(0, os.path.abspath('../'))

# 組込み Sphinx 拡張機能
extensions = ['sphinx.ext.autodoc',
              'sphinx_autodoc_typehints',
              'sphinx.ext.todo',
              'sphinx.ext.viewcode']

Sphinx 프로젝트의 구축

프로젝트 루트에서

$ sphinx-build -a ./docs/ ./docs/html/

또는

$ make html

문서의 첫 페이지docs/html/index.html가 생성됩니다.

Circle CI

Circle CI ver.2의 설정입니다.

프로파일

구성 파일.circleci/config.yml에 문서 생성 및 S3에 배치된 job을 추가합니다.
cofig.yml

version: 2
jobs:
  build:
    docker:
      - image: python:3

    steps:
      - checkout
      - add_ssh_keys:
          fingerprints:
            - "57:f1:**:**:**:**:**:**:**:**:**:**:**:**:**:**"
            - "00:5e:**:**:**:**:**:**:**:**:**:**:**:**:**:**"
      - run:
          name: Build documents
          command: |
            sphinx-build -a ./docs/ ./docs/html/;
            tar cfvz html.tar.gz docs/html/

      - persist_to_workspace:
          root: .
          paths:
            - docs/html/*

  deploy_doc:
    machine:
      enabled: true

    steps:
      - attach_workspace:
          at: html
      - run:
          name: Upload documents
          command: |
            pip install -U awscli;
            aws s3 sync ./html/* s3://<my-bucket>/<my-key>/

workflows:
  version: 2

  build_deploy:
    jobs:
      - build
      - deploy_doc:
          requires:
            - build
          filters:
            branches:
              only: master

workflows

Circle CI2.0에서 workflows를 시작으로 job을 실행합니다.
여기의job는 다음과 같은 두 개가 있다.

문서의 생성(build)

문서 정렬(deploy doc)

또한 문서의 설정job은 다음과 같은 조건을 충족시킬 때 실행됩니다.

빌딩 완성

기본 분기

문서 작성

build job의 주요 부분을 발췌하다.

      - run:
          name: Build documents
          command: |
            sphinx-build -a ./docs/ ./docs/html/;

      - persist_to_workspace:
          root: .
          paths:
            - docs/html/*

sphinx-build을 통해 문서를 만들고 있습니다.
persist_to_workspace는 다음job가 계승한 디렉터리를 기술합니다.
※ 원래 코드 자체는 구축과 테스트를 거쳐야 하는데, 이를 설명하기 위해 생략했습니다.

문서 정렬

deploy_docjob의 주요 부분을 발췌하였다.

  deploy_doc:
    machine:
      enabled: true

    steps:
      - attach_workspace:
          at: html
      - run:
          name: Upload documents
          command: |
            pip install -U awscli;
            aws s3 sync ./html/* s3://<my-bucket>/<my-key>/