運用や開発でまとめた折角のドキュメントが陽の目を見ない(次第に見なくなる)ことはありませんか？
そこで、ドキュメントを利活用しやすい Sphinx をおすすめします。
テキストは簡潔でdiffが取りやすい一方、ドキュメントを見る側に取っては表現が物足りません。
officeファイルは表現力が高いが、diffの表現が難しくなりがちです。
SIerでもSphinxを使いたい！総括
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 形式のキーワードをハイライトする拡張をインストールします。
同梱の README.rst がハイライトになったら成功です。
ドキュメント生成
サンプルプロジェクトでソース作成→ビルド→ドキュメントのプレビューまで確認します。。
プロジェクトの作成
コマンドプロンプトでプロジェクトを作成します。
(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 コマンドで様々なドキュメント形式で出力できることが確認できます。
(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 を使って自動ビルド・プレビュー環境を起動します。
コマンドプロンプトから実行します。
(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チュートリアル
Sphinxの文法を覚える takuan-osho/rst-cheatsheet
rstドキュメントで目次(toctree)の
部->章->セクション->パラグラフは以下の通り使い分けてください
# 部: オーバーライン付き
* 章: オーバーライン付き
=, セクション
-, サブセクション
^, サブサブセクション
", パラグラフ
- Markdownのtoctreeはそれぞれ、以下に対応することに注意してください。
ドキュメントの章立ては
##以降を使いましょう。
# : 目次のタイトル
## : 目次の章
### : 目次の節
入門編を一通り試してみる。 reStructuredText入門
逆引きからやりたいことを調べて書いてみる。 逆引き辞典
プロセスの終了
Ctrl + C で終了します。
[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)
>