前提条件
- Sphinxの利用環境が準備できていること
1. プロジェクトの作成
1.1. プロジェクトディレクトリの作成
変数の設定
DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
&& echo ${DIR_HANDSON}
コマンド
mkdir -p ${DIR_HANDSON}/main \
&& cd ${DIR_HANDSON}/main
(任意) バージョン管理の開始
Marcurialの場合
hg init
コマンド
cat << EOF >> .hgignore
^_build
^_warn.log
\.sw.$
\.DS_Store$
EOF
hg add .hgignore
hg add *
1.2. Sphinxプロジェクト名の決定
変数の設定
SP_PROJECT="Sphinx Handson ($( date +%Y%m%d) )" \
&& echo "${SP_PROJECT}"
1.3. 著者名の決定
変数の設定
SP_AUTHOR='<著者名>'
1.4. プロジェクトのバージョン決定
変数の設定
SP_VERSION='1.0'
1.5. 言語の決定
変数の設定
SP_LANG='ja'
1.6. Sphinxのプロジェクト作成
変数の確認
cat << ETX
SP_PROJECT: ${SP_PROJECT}
SP_AUTHOR: ${SP_AUTHOR}
SP_VERSION: ${SP_VERSION}
SP_LANG: ${SP_LANG}
ETX
コマンド
sphinx-quickstart \
-q \
-p "${SP_PROJECT}" \
-a "${SP_AUTHOR}" \
-v "${SP_VERSION}" \
-l ${SP_LANG}
結果(例)
Finished: An initial directory structure has been created.
You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
注釈: Windows用のmake.batが不要な場合、--no-batchfileを付ける。
コマンド
ls -1F
結果(例)
Makefile
_build/
_static/
_templates/
conf.py
index.rst
make.bat
生成されたファイル
index.rst
ドキュメントの本体となるファイルです。このファイルにドキュメントを記述します。
conf.py
Sphinxの設定ファイルです。Pythonの言語仕様に従って記述します。
Makefile
UNIX系OS用のドキュメントビルドツールです。
make.bat
Windows OS用のドキュメントビルドツールです。
生成されたディレクトリ
_build
ビルドされたドキュメントが格納されます。
_static
静的なファイルを格納します。
_templates
個人的には使ったことないです。
2. ドキュメントの生成
コマンド
make html
結果(例)
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.1
making output directory...
loading translations [ja]... done
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja) ... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
コマンド(全て作り直す場合)
make clean && make html
結果(例)
rm -rf _build/*
sphinx-build -b html -d _build/doctrees . _build/html
(略)
build succeeded.
Build finished. The HTML pages are in _build/html.
生成されたドキュメントは、_build/[形式]の下に置かれます。
コマンド
ls -1F _build/html/
結果(例)
_sources/
_static/
genindex.html
index.html
objects.inv
search.html
searchindex.js
コマンド
cat _build/html/index.html
結果(例)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Welcome to Sphinx Handson (20150720)’s documentation! — Sphinx Handson (20150720) 1.0 ドキュメント</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/translations.js"></script>
<link rel="top" title="Sphinx Handson (20150720) 1.0 ドキュメント" href="#" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>ナビゲーション</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="総合索引"
accesskey="I">索引</a></li>
<li class="nav-item nav-item-0"><a href="#">Sphinx Handson (20150720) 1.0 ドキュメント</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="welcome-to-sphinx-handson-20150720-s-documentation">
<h1>Welcome to Sphinx Handson (20150720)’s documentation!<a class="headerlink" href="#welcome-to-sphinx-handson-20150720-s-documentation" title="このヘッドラインへのパーマリンク">¶</a></h1>
<p>Contents:</p>
<div class="toctree-wrapper compound">
<ul class="simple">
</ul>
</div>
</div>
<div class="section" id="indices-and-tables">
<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="このヘッドラインへのパーマリンク">¶</a></h1>
<ul class="simple">
<li><a class="reference internal" href="genindex.html"><span>索引</span></a></li>
<li><a class="reference internal" href="py-modindex.html"><span>モジュール索引</span></a></li>
<li><a class="reference internal" href="search.html"><span>検索ページ</span></a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="#">目次</a></h3>
<ul>
<li><a class="reference internal" href="#">Welcome to Sphinx Handson (20150720)’s documentation!</a></li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>このページ</h3>
<ul class="this-page-menu">
<li><a href="_sources/index.txt"
rel="nofollow">ソースコードを表示</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>クイック検索</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="検索" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
モジュール、クラス、または関数名を入力してください
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2015, Hirokazu HATANO.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.2</a>
|
<a href="_sources/index.txt"
rel="nofollow">Page source</a></li>
</div>
</body>
</html>
3. Sphinxのカスタマイズ
3.1. Makefileのカスタマイズ
make実行時のエラーログを保存する設定をしておきます。
コマンド
mv Makefile Makefile.org \
&& cat Makefile.org | sed 's/SPHINXOPTS =$/SPHINXOPTS = -w _warn.log/' > Makefile \
&& diff Makefile.org Makefile
結果(例)
5c5
< SPHINXOPTS =
---
> SPHINXOPTS = -w _warn.log
3.2. conf.pyのカスタマイズ
Sphinxの各種設定は conf.py で行います。
- extensions: 拡張の組み込み
- html_theme: テーマ名
- など
設定の追加(サンプル)
cat << EOF >> conf.py
# for HTML
html_theme = 'bizstyle'
html_title = project
# for PDF
language = 'ja'
latex_docclass = {'manual': 'jsbook'}
# define for replace
today_fmt = '%Y-%m-%d'
EOF
cat conf.py
3.3. index.rstのリネーム
このハンズオンではオリジナルのindex.rstは使用しないので、リネームしておきます。
コマンド
mv index.rst origin-index.txt
注釈: Sphinxでは拡張子rstのファイルに対して自動リンクするので、拡張子をtxt に変えておきます。