GitLab PagesでSphinxしたい

.gitlab-ci.yml

image: sphinxdoc/sphinx-latexpdf:latest

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


# ブランチで作業したとき（= PDFは生成しない簡易版）
test:
  script:
    # build HTML pages
    - make html
    - ls -ltr _build/
    - ls -ltr _build/html/
  except:
    - master

# ページを公開する時
pages:
  stage: deploy
  script:
    # build HTML pages
    - make html
    - mv _build/html/ public/
    # build PDF files
    - make latexpdf
    - mv _build/latex public/
  artifacts:
    paths:
      - public
  only:
    - master

公開されるページのURL

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

ポイント

• ローカルで make html と make latexpdf できることが大前提

イメージを取得する

.gitlab-ci.yml

image: sphinxdoc/sphinx-latexpdf:latest

• イメージに sphinxdoc/sphinx-latexpdf を使用
• イメージの取得に約 1.5 分かかる
• LaTeX のコンパイルに約 1.5 分かかる

共通コマンド

.gitlab-ci.yml

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

• テスト（test）とデプロイ（pages）で共通する作業をまとめた
• バージョンの確認などがメインになっている

テスト用

.gitlab-ci.yml

# ブランチで作業したとき（= PDFは生成しない簡易版）
test:
  script:
    # build HTML pages
    - make html
    - ls -ltr _build/
    - ls -ltr _build/html/
  except:
    - master

デプロイ用

.gitlab-ci.yml

# ページを公開する時
pages:
  stage: deploy
  script:
    # build HTML pages
    - make html
    - mv _build/html/ public/
    # build PDF files
    - make latexpdf
    - mv _build/latex public/
  artifacts:
    paths:
      - public
  only:
    - master

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

rules

except/only から rulesに変更

まとめ

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

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