JUS関西 Sphinxワークショップ@関西 Sphinx紹介

1
Takayuki Shimizukawa
Sphinx co-maintainer
Sphinx-users.jp

おまえ誰よ
@shimizukawa（清水川）
 Sphinx メンテナ
 Sphinx-users.jp
 一般社団法人PyCon JP 理事
 Python mini hack-a-thon運営
2

アジェンダ
1. Sphinx概要紹介
2. Sphinxと他のツールを比較
3. Sphinxインストール
4. Sphinx拡張紹介
5. Sphinxの情報源
6. Sphinxデモ
3

Sphinx is 何?
Sphinx はドキュメンテーションジェネレー
タです
SphinxはreSTマークアップから複数の
フォーマットのドキュメントを生成します
5
1. Sphinx紹介
Sphinx
reSTreSTreStructuredText
(reST) reST Parser
HTML Builder
ePub Builder
LaTeX Builder texlive
HTML
theme
Favorite Editor

Sphinx
生成変換
３４
記法
原稿
読込
２
好きなエディタで原
稿を書く
１
Sphinxドキュメントのおおまかな作成フロー
1. Sphinx紹介
6

reSTによるドキュメント作成
 reST = reStructuredText
 http://docs.sphinx-users.jp/rest.html
 テキストでも見やすい形
 見出し
 コードブロック（ハイライト付き）
 文書内／文書外リンク
 表
 toctreeなどを作成する
 ファイル間を繋ぐ「背骨」です（後述）
1. Sphinx紹介
============
大見出し
============
中見出し
=========
小見出し
-------------
-リストアイテム1
-リストアイテム2
#. 自動採番アイテム1
#. 自動採番アイテム2
7
Demo

Step1: Sphinxの初期ドキュメントから始める
C:> sphinx-quickstart
1. Sphinx紹介
8

Step2: ドキュメントの最初のアウトプットを作成
 読者のターゲット別に章節の構成をおおまかに用意
1. Sphinx紹介
9

Step3: 既に分かっている情報を追加
 マネージャー、設計者、開発者それぞれに必要とな
る、
プロジェクト特有の情報を記載
1. Sphinx紹介
10

Step4: 段階的にドキュメントに記載
プロジェクトの進捗と共に
成長するドキュメント
いつドキュメントを更新する？
1. Sphinx紹介
いつでも！
11

各種出力
 HTML以外にもデフォルトでLaTeX、PDF 、ePubに
 HTMLもデフォルトで複数のテーマを使用可
1. Sphinx紹介
$ make latex
$ make latexpdfja
$ make epub
12
Demo

reST原稿と各種出力
1. Sphinx紹介
13

Sphinxの歴史 (ショートver.)
14
1. Sphinx紹介
Ｓｐｈｉｎｘの
父
メンテナンス
が大変
~2007
書きやすく
メンテナンスしやす
い2007~

Sphinx 以前、Sphinx以降
Sphinx以前
 ドキュメントを書く標準的な方法がなかった
 出力フォーマットに合わせて、一度書いたドキュメント
を変換する必要があった
Sphinx以降
 １つのソースから複数フォーマットのドキュメントを生
成
 同梱のHTMLテーマ機能で読みやすいドキュメントを提
供
 APIリファレンスと説明的ドキュメントが同居できる
 自動ビルドとホスティングを提供するReadTheDocsの登 15
1. Sphinx紹介

Sphinxで書かれたドキュメントの例
 Python ライブラリ/ツール:
Python, Sphinx, Flask, Jinja2, Django,
Pyramid, SQLAlchemy, Numpy, SciPy,
scikit-learn, pandas, fabric, ansible, awscli,
…
 Python以外のライブラリ/ツール:
Chef, CakePHP(2.x), MathJax, Selenium,
Varnish
16
1. Sphinx紹介

Sphinxで書かれたドキュメントの例
 Python ライブラリ/ツール:
Python, Sphinx, Flask, Jinja2, Django,
Pyramid, SQLAlchemy, Numpy, SciPy,
scikit-learn, pandas, fabric, ansible, awscli,
…
 Python以外のライブラリ/ツール:
Chef, CakePHP(2.x), MathJax, Selenium,
Varnish
17
1. Sphinx紹介

Sphinxを支えるDocutilsとは
 SphinxはDocutilsライブラリを利用してい
ます
 Docutils/SphinxはreStructuredText(reST)を
サポートしています。reSTは拡張可能な
マークアップ言語です。(PEP287 / 18
1. Sphinx紹介
Sphinx
reST
Parser
HTML Builder
ePub Builder
LaTeX Builder
HTML
theme
docutils

Docutils と Sphinx の機能比較
Docutils Sphinx
1. 単一ページ
2. 他ページへのリンクはファイ
ル名で行う
3. ページ内のクロスリファレン
ス
4. Writers: html, latex, man,
xml, ...
5. 標準reSTマークアップ
1. 複数ページ
2. toctree機能で1つのツリーに全
てのページを接続
3. ページをまたがるクロスリ
ファレンス
4. さらに追加のWriters: html(w/
themes), pdf(latex), texinfo,
epub, …
5. さらに追加のマークアップ
19
1. Sphinx紹介

ドキュメントを書くのに、何を使用していますか？
 ワープロソフト
 Word
 一太郎
 OpenOffice Writer
2. Sphinxと他のツールとの比較
MicrosoftのOfficeの
テンプレートのサイトより転載
21

ワープロソフトのメリット
 縦書きで編集できる
 文法チェックしてくれる
 差分比較機能がある
 参考文献、索引、
差し込み印刷etc…
2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています
か？
22

ワープロソフトのデメリット
 巨大な1ファイルになる
 探すのが大変
 複数人で編集が大変
 章の入れ替えとか厳しい
か？
23

 表計算
 Excel
 Calc
24

表計算のメリット
 Excel扱える人は多い
 ぱっと作るのは早くでき
る
 ロジカルシンキング的に
苦心しなくても、罫線で
武装すると、見た目が立
派に見える
か？
25

表計算のデメリット
 ワークシートで分断され、
閲覧性が悪い
 内容の追加でレイアウト
の修正が必要になると、
修正に膨大な時間がかか
る
か？
26

 それ以外
 Wiki
 HTML手書き
 TeX
 Markdown
27

Wikiのメリット
 圧倒的に柔軟
 構造化されていなくても、とりあえず入れてお
ける
 複数人での編集・閲覧ができる
か？
28

Wikiのデメリット
 文章の構成、質の維持に目を光らせる必要がある
 あるいは、Wikipediaのように構成を決めておく
 全体の構成を修正するのに
手間がかかる
 トップダウン型ではないので、
まとめて印刷や他形式に変換
がやりにくい
か？
29

Markdownのメリット
 書きやすくて読みやすいプレーンテキストとして記
述した文書
 バージョンコントロールOK！
 覚えるべき文法が少ない
 いざとなったらHTMLタグで書ける
 本家Markdown以外の文法（フレーバー）を使えば
表現の幅が広がる
 WYSIWIGエディタがある
か？
30

Markdownのデメリット
 Markdown文法で表現できる範囲が狭い
 ファイルをまたがった参照などがない
 出力フォーマットは（基本）HTMLのみ
 文法に拡張性が無いため、各種フレーバーが乱
立、それぞれに互換性がない
 CommonMark, GitHub-flavored, PHP Markdown
Extra, ...
 単一ページしか扱えない
 Jekyll という Markdownを複数ページで扱うツールが
ある
 Markdown <-> reStructuredText(docutils)
 Jekyll <-> Sphinx
か？
31
Demo

Sphinxのメリット
 書きやすくて読みやすいプレーンテキストとして記
述した文書
 バージョンコントロールOK！
 ドキュメントの背骨がしっかりさせる
 複数ページで構成された大きな文章を扱える
 有機的に文章を繋げる仕組みを持っている
 クロスリファレンス, ドメイン, 用語集, 索引, ...
 複数のフォーマットに出力できる
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird
32
Demo

Sphinxのデメリット
 背骨を気にして、コンテンツを追加する必要
 reStructuredText マークアップを覚える（多い）
 WYSIWIGエディタがない
 拡張を駆使したドキュメントはメンテしづらい
始めるときのハードルが高い
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird
33

$ pip install sphinx
Sphinxのインストール
1. Pythonをインストール(OSによる)
2. Sphinx本体をインストール
35
 Pythonのバージョンに注意して下さい
 SphinxはPython-3でも動作します
 いくつかの拡張はPython-2でしか動作しない場合があ
ります。
 今後、Python-3でしか動作しない拡張も増えていくか
も？
Demo

Sphinx projectの雛形を生成
$ cd /path/to/your-doc
$ sphinx-quickstart
...
Project name: Deep thought
Author name(s): Mice
Project version: 0.7.5
...
...
Finished
36
とりあえずEnter押しておこう
-q オプションで非対話モード
• "-q" といくつかのオプションを指定すると、対話モード
ではなくすぐに雛形が生成されます。
• Sphinx-1.5から"-m" オプションが標準に。Makefileがシ
ンプルになります。
Demo

ファイルの一覧と & conf.pyの設定
$ tree /path/to/your-doc
+- doc
+- _build/
| +- html/
+- _static/
+- _template/
+- conf.py
+- index.rst
+- make.bat
+- Makefile
37
ドキュメントソース
Document build output
1. ...
2.
3. language = 'ja'
4.
doc/conf.py

reStructuredText
(reST)
SphinxreStructuredText
(reST)
reStructuredText
(reST)
で書いた原稿
プロジェクト
HTML生成
(make html)
プロジェクトの作成
(sphinx-quickstart)
設定ファイル
(conf.py)
１
３
原稿の作成と設定
２
sphinx-quickstart から HTML生成まで
38

$ make html
...
Build finished. The HTML pages are in _build/html.
"make html" コマンドで
_build/html ディレクト
リ以下にhtmlファイル
が生成されます
最初のmake html
39
Demo

Sphinxの拡張
Sphinxは拡張(extension)を追加できます。
いくつかの拡張はbuilt-inとして内蔵してお
り、だれでも拡張を作ったり、誰かが公開
している拡張を自由に利用できます。
 読み込みの拡張
 文法の拡張
 ビルダーの拡張
 HTMLテーマの拡張
41
4. Sphinxの拡張
Sphinx
reST Parser
HTML Builder
ePub Builder
LaTeX Builder
docutils
読込の拡張
文法の拡張
ビルダーの拡張
HTMLテーマ
の拡張

SPHINX
docutils
(reST)
reSTParser
(directive/role)
Sphinx拡張
directive/role
* 好きなエディタでreSTを編集
* 好きなツールで画像を作成
* 好きなバージョン管理ツールで更新履歴管理
画像
（ページに埋め込
み）
さまざまな形式で出力
HTML Builder
ePub Builder
LaTeX Builder
HTML theme
(Jinja2)
code highlighter
(Pygments)
doctree
(中間保存)
man, texinfo, text, ...
Builder
gettext Builder
XML, man, texinfo, text,
winhelp, qthelp, ...
TeXLive
等
.pot
.po
多言語化
Sphinx拡張
directive/role
* Sphinxの文法は拡張可能
* 別のマークアップを埋め込み可能
(graphviz, blockdiag, ...)
OmegaT
Pootle
Transifex
翻訳ツール、サービス
任意のエディタ
Sphinx拡張 Builder
拡張Theme
epub3, docx, dash, ...
* 1つのソースから複数の言語で出力する仕組み
* 翻訳はSphinxを知らなくてもできる
（翻訳文章内にreST文法が含まれる場合もある）
* gettext (potファイル)に対応した翻訳ツールや
サービスを使って翻訳ができる
.py
autodoc拡張で
Pythonソースから
ドキュメントを抽出
.mo
内部構成と、周辺との入出力の概要
4. Sphinxの拡張
42

テンプレートの作成
 テンプレートエンジン “Jinja2”を利用している
 大まかに分けて2つのhtmlを作成する
 ドキュメント全体の基礎 : layout.html
 各ページ : page.html
 デフォルトテーマ basic のテンプレート継承により
時間が削減
4. Sphinxの拡張
自分でテンプレートを作成することも可能
43
Demo

Sphinxドメイン
 ある言語を説明するマークアップとSphinx内のオブ
ジェクトのリンク
 Python以外にも多くの言語に対応&独自に作成可能
(Erlang, Ruby, C++, JavaScript…)
 ドキュメント内で相互参照が可能
例) C言語
4. Sphinxの拡張
.. c:function:: int printf(const char *format, …)
44
Demo

組み込みのSphinx拡張
 todo – Todoアイテムのサポート
 autodoc – docstring からの読み込み
 intersphinx – 他のSphinxドキュメントへのリンク
 pngmath – 数式をPNG画像にレンダリング
 jsmath – JavaScriptを用いて数式をレンダリング
 graphviz – Graphvizのグラフを追加
 coverage – ドキュメントのカバレッジ状況の収集
他にも多くの組み込みSphinx拡張あり
4. Sphinxの拡張
45
Demo

サードパーティのSphinx拡張
 blockdiagシリーズ
 blockdiag: ブロック遷移図を簡単な記述だけで作成
 seqdiag: シーケンス図を簡単な記述だけで作成
 actdiag, nwdiag, rackdiag, packetdiag 等
4. Sphinxの拡張
46

blockdiag
 ブロック遷移図を文字のみで書けます
 sphinxcontrib-blockdiag でSphinxでブロック遷移図
を書くことが可能
4. Sphinxの拡張
.. blockdiag::
{
A -> B -> C;
B -> D;
}
47
Demo

seqdiag
 シーケンス図を文字のみで書けます
 sphinxcontrib-seqdiag でSphinxでシーケンスを書く
ことが可能
4. Sphinxの拡張
.. blockdiag::
{
browser -> webserver[label=GET];
browser <-- webserver;
browser -> WebAPI;
}
48

Sphinx i18n機能でのドキュメント翻訳プロセス
49
4. Sphinxの拡張
reST pot
html
po
make gettext
sphinx-intl
make html
ドキュメント作者
翻訳カタログ
翻訳済カタログ
翻訳者
翻訳者
翻訳者
作者 / 翻訳者
アップロード
翻訳者
clone
翻訳者

さまざまな情報源
 イベント
 SphinxCon
 PyCon JP
 Sphinx+翻訳 Hack-a-thon
 Sphinx Tea Night
 ネット
 sphinx, docutils
 sphinx-users.jp
 書籍
 Sphinxをはじめよう (O'reilly)
 SoftwareDesignのSphinx連載2015年4月号～
 他
51
5. Sphinxの情報源

SphinxCon JP 2015
 ２０１２年以降、年に1回開催。
 今年は 11月24日(火) 19時～渋谷にて開催
 プレゼン5つ、LT4つくらい
 Hack-a-thonや
ハンズオンは無し
 参加者（10人～40人）
 ドキュメントに関わる人
 関連ツールに関わる人
 時々出版関係者
52
5. Sphinxの情報源 - イベント
SphinxCon JP 2014
sphinxjp.connpass.com

PyCon JP
53
 Pythonの年次イベント。Sphinx-usres.jp
として参加してイベントを併設しています。pycon.jp/2015/
ポスターセッション
スプリント
ハンズオン（有料）

Sphinx+翻訳 Hack-a-thon
 月1回開催。週末の午後 (6h)
 Sphinxや翻訳に興味のある人が集まって、それぞれ
自分の課題を進めたり、他の人に色々聞いたり、雑
談したり。
 参加者（4人～8人）
 Sphinxに興味のある方
 ドキュメントに興味のある方
 翻訳に興味のある方
 場所: 東京曙橋か新宿の某社
54
sphinxjp.connpass.com
hack-a-thon

Sphinx Tea Night (お茶会)
55
 月1回開催。平日の夜 (2h)
 Sphinxや翻訳に興味のある人が集まって、雑談して
ます。
 参加者（3人～6人）
 Sphinxに興味のある方
 ドキュメントに興味のある方
 なんとなく雑談したい方
 場所: 東京市ヶ谷のデニーズ
Tea Night

Sphinx, docutils本家ドキュメント
56
5. Sphinxの情報源 - ネット
 Sphinx本家: http://sphinx-doc.org/
 Docutils本家: http://docutils.sourceforge.net/
 英語です

 本家ドキュメントにはない、さまざまな情報を複数
の切り口で提供。MLの案内もここに。
 サイト自体Sphinxで作っています
 Twitter: @sphinxjp #sphinxjp
Sphinx-users.jp
57

Sphinx, docutils本家ドキュメントの翻訳
 リファレンスを日本語に翻訳してあります
 Sphinx: http://docs.sphinx-users.jp/ 90%翻訳済み
 Docutils: http://docutils.sphinx-users.jp/ 一部翻訳済
み
58

Sphinxをはじめよう(O'Reilly 2013)
 Sphinx のみを扱った電子書籍
 紙の本で100ページ相当
 Sphinxのインストールから、HTML, PDF, EPUBの出
力方法について、reSTの記法について。
 付録に、よく使うreST
の文法を掲載
 Sphinxを始める人、
必携の書！
59
5. Sphinxの情報源 - 書籍
http://www.oreilly.co.jp/books/9784873116488/

SoftwareDesign Sphinx連載
 2015年4月号～ Sphinx 連載開始！
 6ページ/号, Sphinx短信を不定期掲載
 4月: Sphinxで始めるドキュメント作成術
 5月: 議事録を書こう（前編）
 6月: 議事録を書こう(後編)
 7月: テーブルを使いこなそう
 8月: 目次,用語集,索引を付けよう
 9月: サイトを作ろう(前編)
 10月: サイトを作ろう(後編)
 11月: HTMLテーマをカスタマイズしてみよう
 12月: さまざまな方法で図を作ろう
 1月: テキストマークアップから図を生成する
60
http://gihyo.jp/magazine/SD/archive/2015/201504

エキPy / PyPro1, 2
 いくつかのPythonの本に、Sphinxを扱った章があり
ます。
 コラムで触れている本も含めるともう何冊かありそ
う
61
PyPro 1 エキPy
2012年 2010年
PyPro 2
2015年

まとめ
 Sphinxは
 インストールが簡単
 設定も簡単
 書くのも簡単
 ビルドも簡単
 カスタマイズもできる
 拡張もできる
 サイトも作れる
という素晴らしいドキュメントツールだった！
62

Demoコンテンツ
 sphinx-quickstart
 make html
 言語を日本語に変更
 htmlテーマ変更
 make latexpdfja
 make epub
65

成長のポイント
 背骨
 toctree！toctree！toctree！
 神経のネットワーク
 セマンティックスを定義していく
67

背骨の肝：セクションタイトル
 ドキュメントを構成する重要な要素
 #, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う
 自分なりのルールを決めておくと良い
 単体のソース内の登場順でH1, H2, H3..が決まる
 文字長よりも短いと警告が出ます
========
はじめに
========
想定読者
========
新人社会人
----------
はじめに
想定読者
新人社会人
68

背骨の肝：親子関係の定義
 Sphinxの一番重要な部分
 toctreeディレクティブを使って定義する
 拡張子なしのファイル名を列挙する
 目次がその場で作られる
.. toctree::
:maxdepth: 2
preface
overview/index
defensive/index
 はじめに
 本書の考えるゴール
 本書を作るにあたって
 本書で説明していくこと
 つまみぐい勉強法
 勉強はつまみぐいから
 大切なことは、継続
 自分に合うものを選ぼう
 終着点は自分で決めよう
69

背骨の肝：親子関係の定義
 セクションタイトルを子供の文書から引っ張ってき
て目次を作る
 toctree自体は1文書に何個も書ける
 toctree表示位置に、子供の文書のセクション構造が
挿入される
toctreeができたら、Sphinx黒帯！
70

ドキュメントのモチベーションを上げ
 いろんなやる気のスイッチを活用
 全体像を見て、足りない項目を補完
 とにかく、細かい部分から徹底的に丁寧に
 索引を見て、索引を充実させる
 読む人ごとの入り口を作ってみる
 いろんなフォーマットで出力してみる
71

JUS関西 Sphinxワークショップ@関西 Sphinx紹介

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to JUS関西 Sphinxワークショップ@関西 Sphinx紹介

Similar to JUS関西 Sphinxワークショップ@関西 Sphinx紹介 (20)

More from Takayuki Shimizukawa

More from Takayuki Shimizukawa (20)

Recently uploaded

Recently uploaded (9)

JUS関西 Sphinxワークショップ@関西 Sphinx紹介

Editor's Notes