[Sphinx] Sphinx 프로젝트 온라인 배포 (3)

HTML 문서 게시

 

1) 문서 읽기

 

문서는 GitHub 및 GitLab과의 통합을 제공한다. 시작하는 가장 빠른 방법 은 느슨하게 이 튜토리얼을 기반으로 하는 RTD 튜토리얼을 따르는 것이다. GitHub에 소스를 게시한 다음 문서 읽기 등록으로 바로 건너뛸 수 있다. 대신 GitLab을 선택하면 프로세스가 유사하다.

 

2) GitHub 페이지

 

GitHub 페이지를 사용 하려면 GitHub에 소스를 게시 해야한다. 그 후에 는 소스가 변경될 때마다 단계를 수행하는 자동화된 프로세스가 필요하다. GitHub Actions를 사용하여 달성할 수 있다.

 

GitHub에 소스를 게시한 후 .github/workflows/sphinx.yml 다음 내용으로 리포지토리에 이름이 지정된 파일을 만든다.

 

name: Sphinx build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Build HTML
      uses: ammaraskar/sphinx-action@0.4
    - name: Upload artifacts
      uses: actions/upload-artifact@v1
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

 

여기에는 4단계의 단일 작업이 포함된 GitHub 작업 워크플로가 포함된다.

 

코드를 확인한다. Sphinx를 사용하여 HTML 문서를 빌드한다. 더 쉽게 검사할 수 있도록 HTML 출력을 GitHub Actions 작업에 첨부한다. 기본 브랜치에서 변경 사항이 발생하면 docs/build/html의 내용을 가져와 브랜치로 푸시한다 gh-pages.

 

다음으로 단계가 성공하려면 종속성을 지정해야 한다. 이를 위해 파일 을 만들고 다음 내용을 추가한다.

 

마지막으로 저장소에서 GitHub 페이지를 활성화할 준비가 되었다. 이를 위해 설정 으로 이동한 다음 왼쪽 사이드바에서 페이지gh-pages로 이동 하고 "소스" 드롭다운 메뉴에서 분기를 선택하고 저장 을 클릭한다. 몇 분 후에 지정된 URL에서 HTML을 볼 수 있다.

 

3) GitLab 페이지

 

반면에 GitLab Pages를 사용하려면 GitLab에 소스 를 게시해야 한다. 준비가 되면 GitLab CI를 사용하여 실행 프로세스를 자동화할 수 있다.

 

GitLab에 소스를 게시한 후 다음 내용으로 레포지토리에 gitlab-ci.yml 이름이 지정된 파일을 만든다.

 

stages:
  - deploy

pages:
  stage: deploy
  image: python:3.9-slim
  before_script:
    - apt-get update && apt-get install make --no-install-recommends -y
    - python -m pip install sphinx furo
  script:
    - cd docs && make html
  after_script:
    - mv docs/build/html/ ./public/
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

 

여기에는 여러 단계로 이루어진 하나의 작업이 있는 GitLab CI 워크플로가 포함되어 있다.

 

필요한 종속성을 설치한다. Sphinx를 사용하여 HTML 문서를 빌드한다. 출력을 알려진 아티팩트 위치로 이동한다.

 

그 후 파이프라인이 성공하면 지정된 URL에서 HTML을 볼 수 있어야 한다.

 

https://www.sphinx-doc.org/en/master/tutorial/deploying.html#publishing-your-html-documentation

Appendix: Deploying a Sphinx project online — Sphinx documentation