GitHub Actions、GitHub PagesでSphinxお試し

概要

Sphinx、GitHub Actionsを使用してGitHub Pagesにドキュメントをデプロイするまでをやってみる。

内容

• （参考）Sphinx公式
  • https://www.sphinx-doc.org/ja/master/

リポジトリ作成して、GitHub Pagesの「Source」を「GitHub Actions」に変更。

リポジトリにフォルダやファイルを作成していく。 今回は以下のようなフォルダ構成とした。

• .github/workflows/shinx.ymlにGitHub Actionsで実行する内容を記載
  • python環境にsphinxやsphinxの拡張機能をインストールしている
  • 静的ページの中身ができたらArtifactに登録し、それをPagesに反映している。
  • このあたりの内部挙動がどうなっているのかも勉強したいがとりあえずは動いているのでOK・・・。
• docs以下にsphinxの設定ファイルconf.pyとベースのrstファイルのindex.rstを格納。
  • これらは「sphinx-quickstart」コマンドで作成したものをベースに適当に編集
  • GitHub Actionsではこれらのフォルダの下でドキュメント作成の作業を行う。
• src以下に自作モジュールを格納。
  • 今回は以下からNumpyスタイルのDocStringを持ってきた。
  • https://www.sphinx-doc.org/ja/master/usage/extensions/example_numpy.html

プッシュするとActionsのタブでビルドが走っていることがわかる。

設定からPagesの欄を見ると作成されたページへのリンクがある。

作成されたページは以下。

それっぽいがレイアウトこんな感じだっけ？という箇所もあり。 とりあえずデプロイまではできたのでOKとする・・・。

メモ

以下に公開している。

• リポジトリ
  • https://github.com/anorith347/sphinx-test-minimum
• できたページ
  • https://anorith347.github.io/sphinx-test-minimum/index.html#