GitLab CIしたい（.gitlab-ci.yml）

.gitlab-ci.ymlでGitLab CIを設定することで、Sphinxを使ったGitLab Pagesを自動でビルトできます。 以下は、 シンプルにsphinxdoc/sphinxイメージを使う方法と、 pythonイメージとpoetryを使う方法のサンプルです。

コメントアウトしている部分があったり、デバッグ用の出力があったりしますが、 不要なものは適当にスキップして使ってください。

Sphinxイメージを使いたい

image: sphinxdoc/sphinx:latest
# image: sphinxdoc/sphinx-latexpdf:latest

# stages:
# - test

# sast:
#   stage: test
# include:
# - template: Security/SAST.gitlab-ci.yml

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

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

before_script:
  - python -V
  - pip --version
  - pip install -r requirements.txt


test:
  script:
    - pip install black
    - black --check .
    # build HTML pages
    - cd docs; make dirhtml
    - ls -ltr _build/
    - ls -ltr _build/dirhtml/
  except:
    - master

pages:
  stage: deploy
  script:
    # build HTML pages
    - cd docs; make dirhtml
    - mv _build/dirhtml/ ../public/
    # build PDF
    # - make latexpdf
    # - mv _build/latex public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Sphinx公式のDockerイメージを使うときの設定です。 依存関係はpip install -r requirements.txtで追加インストールしています。 PDFを生成したい場合はイメージをsphinx-latexpdfに変更してください。

Poetryを使いたい

# 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

Poetryで環境構築したい場合の設定です。 ベースはPython公式のDockerイメージを使っています。 そこにvirtualenvで仮想環境を作成した上で、さらにPoetryで環境を構築しています。

依存パッケージにGitHubリポジトリを指定している場合など、pip install -r requirements.txtでは解決できない場合に有効な設定だと思います。