Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
55
Help us understand the problem. What is going on with this article?
@key-amb

Sphinx でドキュメントを作成して GitHub Pages で公開するまで

More than 5 years have passed since last update.

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 で公開するまでの流れでした。

参考

55
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
key-amb
引越しました→ @progrhyme

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
55
Help us understand the problem. What is going on with this article?