GitLab PagesでSphinxしたい

GitLab CI

Poetry + Sphinx でGitLab PagesできるGitLab CIです。

.gitlab-ci.yml

# Official language image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/python/tags/
image: python:latest

# Change pip's cache directory to be inside the project directory since we can
# only cache local items.
variables:
  PIP_CACHE_DIR: '$CI_PROJECT_DIR/.cache/pip'

# Pip's cache doesn't store the python packages
# https://pip.pypa.io/en/stable/reference/pip_install/#caching
#
# If you want to also cache the installed packages, you have to install
# them in a virtualenv and cache it as well.
cache:
  paths:
    - .cache/pip
    - venv/

before_script:
  - python -V # Print out python version for debugging
  - pip install virtualenv
  - virtualenv venv
  - source venv/bin/activate
  - pip install -U pip
  - pip install -U poetry
  - which poetry
  - poetry env info --path
  - poetry install
  #- poetry config virtualenv.in-project true
  #- pip install -r requirements.txt

pages:
  script:
    - cd docs; make dirhtml
    - mv _build/dirhtml/ ../public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

ベース

# Official language image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/python/tags/
image: python:latest

variables:
  PIP_CACHE_DIR: '$CI_PROJECT_DIR/.cache/pip'

cache:
  paths:
    - .cache/pip
    - venv/

ベースはPythonイメージです。
pipとvirtualenvのキャッシュを有効にしています。

Poetry環境を構築する

before_script:
  - python -V # Print out python version for debugging
  - pip install virtualenv
  - virtualenv venv
  - source venv/bin/activate
  - pip install -U pip
  - pip install -U poetry
  - which poetry
  - poetry env info --path
  - poetry install
  #- poetry config virtualenv.in-project true
  #- pip install -r requirements.txt

before_scriptのセクションでPoetry環境を構築します。
GitLab CIではroot権限でのパッケージ追加は非推奨です。
まずvirtualenvで仮想環境を作成したところにpoetryをインストールしています。
続けて、関連パッケージもpoetry installしています。

GitLab Pagesにデプロイする

pages:
  script:
    - cd docs; make dirhtml
    - mv _build/dirhtml/ ../public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Sphinxでドキュメントをビルドします。
GitLab Pagesはpublic/以下のコンテンツを公開するためdocs/_build/dirhtmlを移動（コピーでもOK）しています。

PDFしたい

.gitlab-ci.yml

image: sphinxdoc/sphinx-latexpdf:latest

before_script:
  # テーマをインストールする
  - pip install sphinx_rtd_theme
  # pipのバージョンを確認する
  - pip --version
  # インストール済みのパッケージを確認する
  - pip list --format=columns

PDFを生成するにはLaTeX環境が必要です。
Python + Poetryの方法ではなく、Sphinx公式のLaTeXがはいったイメージ（sphinxdoc/sphinx-latexpdf）をベースにするのがよいと思います。
このイメージは取得に約 1.5 分ほどかかり、LaTeX のコンパイルに約 1.5 分かかりました。

GitLab Pagesで表示したいコンテンツは public に配置する必要があります。
HTMLをビルドしたディレクトリ（_build/html/）を丸ごと public/にして、ウェブサイトを公開
PDF をビルドしたディレクトリ（_build/latex）を丸ごと public/の下に移動してPDF（とその他一式）を公開
（テストしてないけど）PDFだけ移動（mv _build/latex/ドキュメント名.pdf public/） してもOKなはず

• HTML : {GitLab Pages のURL}
• PDF : {GitLab Pages のURL}/latex/ドキュメント名.pdf

まとめ

Sphinxを使ってGitLab Pagesで公開する方法はたくさん見つかるのだが、HTMLとPDFの両方をGitLab Pagesで公開する方法はなかなか見つけることができなかった。

Sphinx公式の Docker イメージを使って.gitlab-ci.ymlを整えてみたら、とても簡単にできることが分かった 💡・・・ものすごく簡単なので、誰も記事にしていなかったのかもしれない 🐻