Open9
Sphinx と GitHub Pages によるドキュメント生成とホスティング
scaSphinx のインストール
% pip install sphinx
Sphinx のセットアップ
% sphinx-quickstart <target>
sphinx-quickstart で Sphinx の初期設定を対話的に行うことができる。<target> で指定されたディレクトリの下に Sphinx のファイルが生成される。省略するとカレントディレクトリの下に作られる。今回は docs_src 以下にファイルを作る。
実行後、以下のようなファイルが生成される。
docs_src
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
ドキュメントの生成 (ビルド)
# docs_src ディレクトリ内で実行
% make html
build/html の下に HTML ファイルが生成される。
build/html
├── _sources
│ └── index.rst.txt
├── _static
│ ├── alabaster.css
│ ├── basic.css
│ ├── custom.css
│ ├── doctools.js
│ ├── documentation_options.js
│ ├── file.png
│ ├── language_data.js
│ ├── minus.png
│ ├── plus.png
│ ├── pygments.css
│ ├── searchtools.js
│ └── sphinx_highlight.js
├── genindex.html
├── index.html
├── objects.inv
├── search.html
└── searchindex.js
ビルド出力先の変更
いまプロジェクトディレクトリが以下のようになっていて、docs_src が Sphinx のルートディレクトリだとする。
sphinx-example
├── docs
└── docs_src
GitHub Pages にホスティングするため、HTML の出力先をデフォルトの docs_src/build/html から docs ディレクトリに変更したい。そこで Makefile に以下を追加する。
Makefile
html: Makefile
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "../docs" $(SPHINXOPTS) $(O)
参考資料: GitHub Actionsを用いてGitHub Pagesへのデプロイを自動化する — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
sca.nojekyll の設定
conf.py に以下を追加する。
conf.py
extensions = [
"sphinx.ext.githubpages"
]
参考資料: SphinxでビルドしたHTMLをGitHub Pagesで公開するときの頼れる味方、sphinx.ext.githubpagesを知っていますか？ - nikkie-ftnextの日記
scaGitHub Pages にホスティング
- GitHub Pages の設定
- Settings > Pages
- Soruce を "Deploy from a branch" にする
- ソースに "main" ブランチの "/docs" を指定して Save
- Sphinx プロジェクトを GitHub に push
以上で、Sphinx で生成した HTML ファイルが GitHub Pages で見えるようになる。
sca次にやること:
- GitHub Actions によるデプロイの自動化 (
doc_src以下を更新して push したら自動で html をビルドしてほしい)