Windows環境でメンテしやすいドキュメントをSphinxで作る(rst形式, Markdown形式)

運用や開発でまとめた折角のドキュメントが陽の目を見ない(次第に見なくなる)ことはありませんか？
そこで、ドキュメントを利活用しやすい [Sphinx](http://sphinx-users.jp/) をおすすめします。

テキストは簡潔でdiffが取りやすい一方、ドキュメントを見る側に取っては表現が物足りません。
officeファイルは表現力が高いが、diffの表現が難しくなりがちです。
[SIerでもSphinxを使いたい！総括
](https://www.slideshare.net/kk_Ataka/20141026-sphinx-forsiersummarysiersphinx)

Sphinxは独自構文が多いためソースの可読性は落ちますが、ビルドでHTMLやPDFとして簡単に出力できます。
検索も簡単です。

本投稿ではローカルでドキュメントをビルドする所までを示します。

# TL; DR

・ドキュメント執筆環境を準備する
・ソースから、ローカルでドキュメントを自動ビルドする
・(導入後)書けば書くほどドキュメントが更新されてメンテされていく

# 環境
Windows: 8.1
python: 3.6.0
エディタ:サクラエディタ 2.2.0.1

# インストール

## Python3

Windows版の最新をダウンロードする。
https://www.python.org/downloads/ 

## Sphinxライブラリ

`virtualenvwrapper` でsphinx専用のビルド環境を整えて、ライブラリを導入します。
コマンドプロンプトで作業を行います。

```
>pip install virtualenvwrapper
>mkvirtualenv sphinx
Using base prefix 'c:\\users\\<username>\\appdata\\local\\programs\\python\\python36'
New python executable in C:\Users\<username>\Envs\test\Scripts\python.exe
Installing setuptools, pip, wheel...done.
>(sphinx)pip install Sphinx Sphinx-autobuild sphinx_rtd_theme commonmark==0.5.5 sphinxcontrib-actdiag sphinxcontrib-blockdiag sphinxcontrib-nwdiag sphinxcontrib-seqdiag recommonmark==0.4.0
```

## シンタックスハイライトの導入
サクラエディタで `rst` 形式のキーワードをハイライトする拡張をインストールします。

[第3日目 Sphinxドキュメントを書く道具](http://advent-calendar2012.usaturn.net/2012/12/03/writing_tool.html)

同梱の `README.rst` がハイライトになったら成功です。

# ドキュメント生成

サンプルプロジェクトでソース作成→ビルド→ドキュメントのプレビューまで確認します。。

## プロジェクトの作成

コマンドプロンプトでプロジェクトを作成します。

```console
(sphinx) 
> sphinx-quickstart                                                                                                  
Welcome to the Sphinx 1.5.3 quickstart utility.                                                                      
                                                                                                                     
Please enter values for the following settings (just press Enter to                                                  
accept a default value, if one is given in brackets).                                                                
                                                                                                                     
Enter the root path for documentation.                                                                               
> Root path for the documentation [.]:                                                                               
                                                                                                                     
You have two options for placing the build directory for Sphinx output.                                              
Either, you use a directory "_build" within the root path, or you separate                                           
"source" and "build" directories within the root path.                                                               
> Separate source and build directories (y/n) [n]: y   # => ソースとビルドディレクトリの分離
                                                                                                                     
Inside the root directory, two more directories will be created; "_templates"                                        
for custom HTML templates and "_static" for custom stylesheets and other static                                      
files. You can enter another prefix (such as ".") to replace the underscore.                                         
> Name prefix for templates and static dir [_]:                                                                      
                                                                                                                     
The project name will occur in several places in the built documentation.                                            
> Project name: sample    # => プロジェクト名。ビルドしたドキュメントに表示される
> Author name(s): author  # => 著者名。ビルドしたドキュメントに表示される
                                                                                                                     
Sphinx has the notion of a "version" and a "release" for the                                                         
software. Each version can have multiple releases. For example, for                                                  
Python the version is something like 2.5 or 3.0, while the release is                                                
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,                                               
just set both to the same value.                                                                                     
> Project version []: 0.1      # => バージョン名。
> Project release [0.1]: 0.1   # => プロジェクト名。
                                                                                                                     
If the documents are to be written in a language other than English,                                                 
you can select a language here by its language code. Sphinx will then                                                
translate text that it generates into that language.                                                                 
                                                                                                                     
For a list of supported codes, see                                                                                   
http://sphinx-doc.org/config.html#confval-language.                                                                  
> Project language [en]: ja   # => 言語名
                                                                                                                     
The file name suffix for source files. Commonly, this is either ".txt"                                               
or ".rst".  Only files with this suffix are considered documents.                                                    
> Source file suffix [.rst]: # => 入力のソース拡張子。
                                                                                                                     
One document is special in that it is considered the top node of the                                                 
"contents tree", that is, it is the root of the hierarchical structure                                               
of the documents. Normally, this is "index", but if your "index"                                                     
document is a custom template, you can also set this to another filename.                                            
> Name of your master document (without suffix) [index]:  # => ルートのソースドキュメント。この場合は index.rst がルート
                                                                                                                     
Sphinx can also add configuration for epub output:                                                                   
> Do you want to use the epub builder (y/n) [n]:                                                                     
                                                                                                                     
Please indicate if you want to use one of the following Sphinx extensions:                                           
> autodoc: automatically insert docstrings from modules (y/n) [n]:                                                   
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:                                             
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:                                    
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:                                         
> coverage: checks for documentation coverage (y/n) [n]:                                                             
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:                                                    
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:                                               
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:                                       
> viewcode: include links to the source code of documented Python objects (y/n) [n]:                                 
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:                              
                                                                                                                     
A Makefile and a Windows command file can be generated for you so that you                                           
only have to run e.g. `make html' instead of invoking sphinx-build                                                   
directly.                                                                                                            
> Create Makefile? (y/n) [y]:                                                                                        
> Create Windows command file? (y/n) [y]:                                                                            
                                                                                                                     
Creating file .\source\conf.py.                                                                                      
Creating file .\source\index.rst.                                                                                    
Creating file .\Makefile.                                                                                            
Creating file .\make.bat.                                                                                            
                                                                                                                     
Finished: An initial directory structure has been created.                                                           
                                                                                                                     
You should now populate your master file .\source\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.                                     
>                                                                                                                    
```

プロジェクトが生成されると、`make` コマンドで様々なドキュメント形式で出力できることが確認できます。

```console
(sphinx)                             
> make                                                                         
Sphinx v1.5.3                                                                  
Please use `make target' where target is one of                                
  html        to make standalone HTML files                                    
  dirhtml     to make HTML files named index.html in directories               
  singlehtml  to make a single large HTML file                                 
  pickle      to make pickle files                                             
  json        to make JSON files                                               
  htmlhelp    to make HTML files and an HTML help project                      
  qthelp      to make HTML files and a qthelp project                          
  devhelp     to make HTML files and a Devhelp project                         
  epub        to make an epub                                                  
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter        
  text        to make text files                                               
  man         to make manual pages                                             
  texinfo     to make Texinfo files                                            
  gettext     to make PO message catalogs                                      
  changes     to make an overview of all changed/added/deprecated items        
  xml         to make Docutils-native XML files                                
  pseudoxml   to make pseudoxml-XML files for display purposes                 
  linkcheck   to check all external links for integrity                        
  doctest     to run all doctests embedded in the documentation (if enabled)   
  coverage    to run coverage check of the documentation (if enabled)          
                                                                               
(sphinx)
>
```

プロジェクトは `Separate source and build directories (y/n) => y` を選択すると、 `build` と `source` に分かれています。

目的ごとに分けたい場合は、 `source/hoge` のようにディレクトリで分けていきます。

```
├─build            # ビルドしたドキュメントが出力される
└─source           # ソースのルート
    ├─_static
    └─_templates
```

## Markdown対応

Markdown形式(.md)も入力ソースとして扱えるように設定します。
`source/conf.py` を修正します。

diag関係のパッケージも追加したので取り扱えるようにします．

```
-extensions = []
+extensions = [
+    'sphinxcontrib.blockdiag',
+    'sphinxcontrib.seqdiag',
+    'sphinxcontrib.actdiag',
+    'sphinxcontrib.nwdiag',
+    'sphinxcontrib.rackdiag',
+    'sphinxcontrib.packetdiag',
+]
-source_suffix = ['.rst']
+source_suffix = ['.rst', '.md']
+source_parsers = {
+    '.md' : 'recommonmark.parser.CommonMarkParser'
+}
```

## ドキュメント執筆環境の実行

`sphinx-autobuild` を使って自動ビルド・プレビュー環境を起動します。
コマンドプロンプトから実行します。

```console
(sphinx)
> sphinx-autobuild source build

+--------- manually triggered build ---------------------------------------------
| Running Sphinx v1.5.3
| 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.
+--------------------------------------------------------------------------------

[I 170331 16:19:37 server:283] Serving on http://127.0.0.1:8000
[I 170331 16:19:37 handlers:60] Start watching changes
[I 170331 16:19:37 handlers:62] Start detecting changes
```

ブラウザで `http://127.0.0.1:8000` アクセスして、 `Welcome to sample’s documentation!` が表示されたら完了です。

あとはドキュメントをどんどん書いていきましょう。

## 書き方を覚える

- Sphinxの実行環境を用意する [Sphinxチュートリアル](https://map.repos.xad300.goo.ne.jp/svn/teams/B0_tool/sphinx/Sphinxチュートリアル.md)

- Sphinxの文法を覚える [takuan-osho/rst-cheatsheet](https://github.com/takuan-osho/rst-cheatsheet/blob/japanese/rst-cheatsheet.rst)

- rstドキュメントで目次(toctree)の ``部->章->セクション->パラグラフ`` は以下の通り使い分けてください

```    
# 部: オーバーライン付き
* 章: オーバーライン付き
=, セクション
-, サブセクション
^, サブサブセクション
", パラグラフ
```

- Markdownのtoctreeはそれぞれ、以下に対応することに注意してください。
ドキュメントの章立ては `##` 以降を使いましょう。

```
#   : 目次のタイトル
##  : 目次の章
### : 目次の節
```

- 入門編を一通り試してみる。 [reStructuredText入門](http://docs.sphinx-users.jp/rest.html)

- 逆引きからやりたいことを調べて書いてみる。 [逆引き辞典](http://sphinx-users.jp/reverse-dict/index.html>)

## プロセスの終了

`Ctrl + C`  で終了します。

```console
[I 170331 16:23:49 server:283] Serving on http://127.0.0.1:8000
[I 170331 16:23:49 handlers:60] Start watching changes
[I 170331 16:23:49 handlers:62] Start detecting changes
[I 170331 16:23:50 handlers:133] Browser Connected: http://127.0.0.1:8000/
[I 170331 16:23:54 server:303] Shutting down...

(sphinx)
>
```

# 参考

- [Sphinx with Markdown](https://speakerdeck.com/shirou/sphinx-with-markdown)
- [MarkdownでSphinxできるようになったので試してみた（後編）](http://tech.3rd-p-zombie.net/entry/2015/12/02/023732)
- [自分用技術メモの作成が捗ったSphinxのあれこれについて](http://qiita.com/satake_masaki/items/7f73873809feab363b9f)
- [SphinxでMarkdownを使うときに注意すること](http://qiita.com/tk_wada/items/0991b1f5148b665f261d)
- [ドキュメントの継続的な開発方法](http://eng-blog.iij.ad.jp/archives/16)
- [Sphinxでblockdiagを使って簡単にシーケンス図、ブロック図を含めたHTMLベースのドキュメントを生成する環境を整える](https://qiita.com/yamionp/items/8f8d52d6b41bf9d4d16d)