[Sphinx] #1 Sphinx Quick Start

# 前提条件

- Sphinxの利用環境が準備できていること
    - 参考: http://qiita.com/tcsh/items/ce758fd45f748463c4b9#%E7%92%B0%E5%A2%83%E6%A7%8B%E7%AF%89-%E5%8F%82%E8%80%83


1. プロジェクトの作成
=====================


1.1. プロジェクトディレクトリの作成
-----------------------------------

```bash:変数の設定:
DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
     && echo ${DIR_HANDSON}
```

```bash:コマンド:
mkdir -p ${DIR_HANDSON}/main \
     && cd ${DIR_HANDSON}/main
```


(任意) バージョン管理の開始
---------------------------

```bash:Marcurialの場合:
hg init
```

```bash:コマンド:
cat << EOF >> .hgignore
^_build
^_warn.log
\.sw.$
\.DS_Store$
EOF

hg add .hgignore
hg add *
```


1.2. Sphinxプロジェクト名の決定
-------------------------------

```bash:変数の設定:
SP_PROJECT="Sphinx Handson ($( date +%Y%m%d) )" \
     && echo "${SP_PROJECT}"
```


1.3. 著者名の決定
-----------------

```bash:変数の設定:
SP_AUTHOR='<著者名>'
```


1.4. プロジェクトのバージョン決定
---------------------------------

```bash:変数の設定:
SP_VERSION='1.0'
```


1.5. 言語の決定
---------------

```bash:変数の設定:
SP_LANG='ja'
```


1.6. Sphinxのプロジェクト作成
-----------------------------

```bash:変数の確認:
cat << ETX

     SP_PROJECT: ${SP_PROJECT}
     SP_AUTHOR:  ${SP_AUTHOR}
     SP_VERSION: ${SP_VERSION}
     SP_LANG:    ${SP_LANG}

ETX
```

```bash:コマンド:
sphinx-quickstart \
  -q \
  -p "${SP_PROJECT}" \
  -a "${SP_AUTHOR}" \
  -v "${SP_VERSION}" \
  -l ${SP_LANG}
```

```text:結果(例):
   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を付ける。

```bash:コマンド:
ls -1F
```

```text:結果(例):
   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. ドキュメントの生成
=====================

```bash:コマンド:
make html
```

```text:結果(例):
   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.
```

```bash:コマンド(全て作り直す場合):
make clean && make html
```

```text:結果(例):
   rm -rf _build/*
   sphinx-build -b html -d _build/doctrees   . _build/html
   (略)
   build succeeded.

   Build finished. The HTML pages are in _build/html.
```

生成されたドキュメントは、_build/[形式]の下に置かれます。

```bash:コマンド:
ls -1F _build/html/
```

```text:結果(例):
   _sources/
   _static/
   genindex.html
   index.html
   objects.inv
   search.html
   searchindex.js
```

```bash:コマンド:
cat _build/html/index.html
```

```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! &mdash; 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> &raquo;</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)&#8217;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)&#8217;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">
         &copy;2015, Hirokazu HATANO.
         
         |
         Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a>
         &amp; <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実行時のエラーログを保存する設定をしておきます。

```bash:コマンド:
mv Makefile Makefile.org \
   && cat Makefile.org | sed 's/SPHINXOPTS    =$/SPHINXOPTS    = -w _warn.log/' > Makefile \
   && diff Makefile.org Makefile
```

```text:結果(例):
   5c5
   < SPHINXOPTS    =
   ---
   > SPHINXOPTS    = -w _warn.log
```


3.2. conf.pyのカスタマイズ
--------------------------

Sphinxの各種設定は conf.py で行います。

* extensions: 拡張の組み込み
* html_theme: テーマ名
* など

```bash:設定の追加(サンプル):
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は使用しないので、リネームしておきます。

```bash:コマンド:
mv index.rst origin-index.txt
```

注釈: Sphinxでは拡張子rstのファイルに対して自動リンクするので、拡張子をtxt に変えておきます。


完了
=====