🏝

GitLab PagesでSphinxしたい

2022/01/20に公開約1,300字
.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

公開されたページ

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

ポイント

  • ローカルで make htmlmake latexpdf できることが大前提
  • イメージに sphinxdoc/sphinx-latexpdf を使用
    • イメージの取得に約 1.5 分かかる
    • LaTeX のコンパイルに約 1.5 分かかる
  • GitLab Pages で表示/アクセスしたいコンテンツは public に配置
    • HTML をビルドしたディレクトリ(_build/html/)を丸ごと public/にしてしまえば OK
    • PDF をビルドしたディレクトリ(_build/latex)を丸ごと public/の下に移動してしまえば OK
  • (テストしてないけど)
    • PDF だけ移動(mv _build/latex/ドキュメント名.pdf public/) しても OK なはず

まとめ

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

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

Discussion

ログインするとコメントできます