Python 製ドキュメンテーションツールの Sphinx を使ってドキュメントを作成し、GitHub Pagesに公開するまでの手続きです。
なお、Sphinx-Users.jpによる手順も公開されていますので、そちらを参照してもよいでしょう。
Mac OS X 上の pyenv 環境で実施しましたが、多くの手順は環境によらないでしょう。
事前準備
GitHub 上でドキュメント用のリポジトリを作成しておきます。
以降ではこのリポジトリを仮に bob/foo-doc として扱います。
Sphinx Install
チュートリアルに従って、Sphinx のインストールから実施していきます。
% pip install Sphinx
雛形の生成
% sphinx-quickstart
いくつか(というかかなりの数の)オプションを訊かれます。
最低限、autodoc 拡張については "YES" と答えればいいようです。
また、ドキュメントのソースコードとビルド生成物のディレクトリを分けたかったので、"Separate source and build directories (y/n) [n]?" という問いに対しても "YES" としました。
完了すると次のようなディレクトリ構造が生成されます。
% tree .
.
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
後で build/html/ 以下を GitHub Pages で公開するために、予め .gitignore に設定しておきましょう。
% echo 'build/html/' >> .gitignore
ソースコードは適当なタイミングで GitHub に push しておくといいです。
master ブランチのままでも、source というブランチ名にしてもいいでしょう。
build 実行
Makefile を見るといくつかのタスクが登録されていることがわかります。
ここではスタンドアローンのHTMLドキュメントを生成します。
% make html
build/html/ 以下に HTML 群が生成されます。
% tree build/
build/
├── doctrees
│ ├── environment.pickle
│ └── index.doctree
└── html
├── _sources
│ └── index.txt
├── _static
│ ├── ajax-loader.gif
│ :
│ ├── jquery.js
│ :
│ └── websupport.js
├── genindex.html
├── index.html
├── objects.inv
├── search.html
└── searchindex.js
ローカルPC上で見るならこれだけでもいいのですが、今回は build/html/ 以下を GitHub Pages で公開します。
build/html/ 以下で git init し、リポジトリの gh-pages ブランチに push しましょう。
% cd build/html/
% git init
% git checkout -b gh-pages
% git commit -a -m "first commit"
% git remote add origin git@github.com:bob/foo-doc.git
% git push -u origin gh-pages
この結果、http://bob.github.io/foo-doc/ で HTML ドキュメントが閲覧可能になります。
ただし、このままでは GitHub Pages で使われている Jekyll の仕様で _static/ 配下の画像やCSSが読み込まれません。
この動作を抑制するため、.nojekyll というファイルを配置しておきましょう。
% touch .nojekyll
% git commit -a -m "Add .nojekyll"
% git push origin gh-pages
以上、Sphinx でドキュメントを作成して、GitHub Pages で公開するまでの流れでした。