2021年9月20日月曜日

github pages のドキュメントを sphinx で作成

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 で公開することができました。


sphinx ドキュメントを更新する場合

以下の順序で実施します。

  1. doc/source/ 配下のドキュメントを更新
  2. doc/ で make html
  3. 上記の [gh-pages ブランチを commit] を実施
  4. 上記の [main ブランチを commit]

新たにリポジトリを clone する場合

gh-pages リポジトリをサブモジュールとして割り当てられた test リポジトリを新たに clone する場合は以下の順序で実施します。

  1. test リポジトリを clone
  2. サブモジュールを update
    $ cd test/
    $ git submodule update --init
    
  3. サブモジュールのディレクトリに移動して gh-pages ブランチにチェックアウト
    $ cd doc/build/html/
    $ git checkout gh-pages
    

参考