github pages のドキュメントを sphinx で作成する方法はググるといろいろあるようですが、今回は以下を参考にしてみました。
github ではリポジトリの gh-pages ブランチを github pages として公開することができるので、main ブランチの sphinx の build/html/ に同リポジトリの gh-pages ブランチをサブモジュールとして割り当てます。
環境
- Ubuntu 20.04.3 LTS
- Sphinx 4.2.0
github でリポジトリを用意
github で新しくリポジトリを新規作成しました。リポジトリ名は test としています。
ローカルの Ubuntu にリポジトリをクローン
$ cd ~
$ git clone https://github.com/nezuppo/test.git
gh-pages ブランチを作成
git の test リポジトリのディレクトリに移動
$ cd ~/test/
–orphan オプションを付けて何も commit されていない gh-pages ブランチを作成してチェックアウト
$ git checkout --orphan gh-pages
Switched to a new branch 'gh-pages'
一応 git-branch で確認すると orphan だからなのか gh-pages ブランチは出てこず、以下のような出力となりました。
$ git branch -a
main
remotes/origin/HEAD -> origin/main
remotes/origin/main
ファイルは main ブランチと同じのものがありましたが、commit 前の状態でした。
$ ls -la
total 16
drwxr-xr-x 3 test test 4096 Sep 19 22:46 .
drwxr-xr-x 8 test test 4096 Sep 19 22:55 ..
drwxr-xr-x 8 test test 4096 Sep 19 23:16 .git
-rw-r--r-- 1 test test 6 Sep 19 22:46 README.md
$ git status
On branch gh-pages
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: README.md
まずは空の状態にしました。
$ rm README.md
$ git rm --cached README.md
rm 'README.md'
$ ls -la
total 12
drwxr-xr-x 3 test test 4096 Sep 19 23:20 .
drwxr-xr-x 8 test test 4096 Sep 19 22:55 ..
drwxr-xr-x 8 test test 4096 Sep 19 23:21 .git
$ git status
On branch gh-pages
No commits yet
nothing to commit (create/copy files and use "git add" to track)
空の状態だと github に push できないので .nojekyll ファイルを追加し push までしました。なお、github pages でデフォルトで有効になっている Jekyll ツールが sphinx ドキュメントとの相性が悪いようなので .nojekyll ファイルで無効にする必要があるとのことです。
$ touch .nojekyll
$ git add .nojekyll
$ git commit
$ git push --set-upstream origin gh-pages
この状態で github の test リポジトリの [Settings] - [Pages] で確認すると Source が gh-pages リポジトリの / (root) となっていました。
main ブランチ配下に gh-pages ブランチをサブモジュールとして割り当て
main ブランチの doc/ に sphinx を展開し、html ファイル一式が置かれる doc/build/html/ に gh-pages ブランチをサブモジュールとして割り当てます。これにより gh-pages ブランチ の / (root) に sphinx ドキュメントの html ファイル一式が置かれ github pages で公開されるようになります。
main ブランチの / (root) に移動
$ cd ~/test
$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
サブモジュール用のディレクトリを作成
$ mkdir -p doc/build
gh-pages ブランチをサブモジュールとして割り当て
$ git submodule add -b gh-pages https://github.com/nezuppo/test.git doc/build/html
doc/ に sphinx を展開
doc/ に移動
$ cd doc
sphinx を展開。以下のように source と build ディレクトリは分割させました。
$ sphinx-quickstart
(省略)
> Separate source and build directories (y/n) [n]: y
(省略)
この状態で make clean すると build 配下がサブモジュール化された状態も含め全て削除されてしまい都合が悪いので Makefile を以下のように修正。ついでに make clean と make html、make help 以外は使えないようにしました。
$ diff -U -1 Makefile{.org,}
--- Makefile.org 2021-09-20 00:14:36.590000000 +0900
+++ Makefile 2021-09-20 00:15:43.500000000 +0900
@@ -1,20 +1,25 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
+clean:
+ rm -rf $(BUILDDIR)/html/*
+ rm -rf $(BUILDDIR)/html/.buildinfo
+ rm -rf $(BUILDDIR)/doctrees
+
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+html:
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
また、sphix のテーマは bizstyle が好みなの以下のようにで変更しました。
$ diff -U 0 source/conf.py{.org,}
--- source/conf.py.org 2021-09-20 00:21:20.030000000 +0900
+++ source/conf.py 2021-09-20 00:21:58.500000000 +0900
@@ -54 +54 @@
-html_theme = 'alabaster'
+html_theme = 'bizstyle'
html ドキュメントを生成
$ make html
build/html/ 配下に github pages で公開する html ドキュメントが生成されました。
$ ls -la build/html/
total 48
drwxr-xr-x 4 test test 4096 Sep 20 00:23 .
drwxr-xr-x 4 test test 4096 Sep 20 00:23 ..
-rw-r--r-- 1 test test 230 Sep 20 00:23 .buildinfo
-rw-r--r-- 1 test test 45 Sep 19 23:59 .git
-rw-r--r-- 1 test test 0 Sep 19 23:59 .nojekyll
drwxr-xr-x 2 test test 4096 Sep 20 00:23 _sources
drwxr-xr-x 2 test test 4096 Sep 20 00:23 _static
-rw-r--r-- 1 test test 3070 Sep 20 00:23 genindex.html
-rw-r--r-- 1 test test 4484 Sep 20 00:23 index.html
-rw-r--r-- 1 test test 269 Sep 20 00:23 objects.inv
-rw-r--r-- 1 test test 3437 Sep 20 00:23 search.html
-rw-r--r-- 1 test test 598 Sep 20 00:23 searchindex.js
gh-pages ブランチを commit
main ブランチより先に gh-pages ブランチを commit する必要があるようです。
gh-pages ブランチを割り当てたサブモジュールディレクトリに移動
$ cd ~/test/doc/build/html/
ブランチが gh-pages であることを確認
$ git branch
* gh-pages
main
git インデックスに追加
$ git add *
$ git add .buildinfo
commit
$ git commit
git status でコミット漏れがないことを確認して push
$ git status
On branch gh-pages
Your branch is ahead of 'origin/gh-pages' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
$ git push
main ブランチを commit
gh-pages ブランチの次に main ブランチを commit します。
test リポジトリの / (root) に移動
$ cd ~/test
ブランチが main であることを確認
$ git branch
gh-pages
* main
git インデックスに追加
$ git add doc/build/html/
$ git add doc/
commit
$ git commit
git status でコミット漏れがないことを確認して push
$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
$ git push
github pages を確認
これで sphinx ドキュメントの html ファイル一式を github pages で公開することができました。
- github pages URL: https://nezuppo.github.io/test/
sphinx ドキュメントを更新する場合
以下の順序で実施します。
- doc/source/ 配下のドキュメントを更新
- doc/ で make html
- 上記の [gh-pages ブランチを commit] を実施
- 上記の [main ブランチを commit]
新たにリポジトリを clone する場合
gh-pages リポジトリをサブモジュールとして割り当てられた test リポジトリを新たに clone する場合は以下の順序で実施します。
- test リポジトリを clone
- サブモジュールを update
$ cd test/ $ git submodule update --init - サブモジュールのディレクトリに移動して gh-pages ブランチにチェックアウト
$ cd doc/build/html/ $ git checkout gh-pages
