GitLab CIしたい（.gitlab-ci.yml）
GitLab CIを設定することで、Sphinxで生成したドキュメントを
GitLab Pagesに自動で公開できるようになります。
設定は.gitlab-ci.ymlに記述します。
以下では、
sphinxdoc/sphinxイメージを使う方法と、
pythonイメージでpoetryを使う方法のサンプルです。
コメントアウトしている部分があったり、デバッグ用の出力があったりしますが、 不要なものは適当にスキップして使ってください。
Sphinxイメージを使いたい
# 環境変数の設定
variables:
PIP_CACHE_DIR: '$CI_PROJECT_DIR/.cache/pip'
# キャッシュするパスの設定
cache:
paths:
- .cache/pip
- venv/
default:
image: sphinxdoc/sphinx:latest
# image: sphinxdoc/sphinx-latexpdf:latest
before_script:
- python -V
- pip --version
- pip install virtualenv
- virtualenv venv
- source venv/bin/activate
- pip install -U pip
- pip install -r requirements.txt
test:
script:
# build HTML pages
- cd docs; make dirhtml
- ls -ltr _build/
- ls -ltr _build/dirhtml/
rules:
- if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
pages:
stage: deploy
script:
# build HTML pages
- cd docs
- make dirhtml
- mv _build/dirhtml/ ../public/
# - make latexpdf
# - mv _build/latex/ファイル名.pdf ../public/
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
Sphinx公式のDockerイメージを使うときの設定です。
依存関係はpip install -r requirements.txtで追加インストールしています。
PDFを生成したい場合はイメージをsphinx-latexpdfに変更してください。
Python + Poetryを使いたい
# 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
cache:
paths:
- .cache/pip
- venv/
default:
# 利用するイメージを設定
# Pythonのバージョンは以下で確認
# https://hub.docker.com/r/library/python/tags/
image: python:3.12
# ジョブの前に実行するスクリプトを設定
# virtualenvで仮想環境を作成し、そこのpoetryを追加
# poetry install で関係するパッケージを追加
# APIドキュメントのときは poetry install する
# ただのドキュメントの poetry install --no-root でもOK
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 install --no-root
# デフォルトブランチ以外にプッシュがあった場合：
# ページがビルドできるかだけ確認する
# （ページを公開しない）
test:
script:
- poetry show --outdated
- cd docs; make dirhtml; cd ..;
- ls -ltr docs/_build/dirhtml/
rules:
- if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
# デフォルトブランチにプッシュ（やマージリクエスト）があった場合：
# ページをビルドし、GitLab Pagesに公開する
# "public"というartifactで公開している
pages:
stage: deploy
script:
- cd docs; make dirhtml; cd..;
- mv docs/_build/dirhtml/ public/
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
Python + Poetryで環境構築する場合の設定です。
ベースとなるイメージはPython公式のDockerイメージを使っています。
root権限でpipすると警告が表示されるため、
virtualenvで仮想環境を作成した上に
Poetryで環境を構築しています。