Transcript
Sphinx 紹介-JUS 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
1. Sphinx 紹介
4
Sphinx is 何 ?
Sphinx はドキュメンテーションジェネレータですSphinx は reST マークアップから複数のフォーマットのドキュメントを生成します
5
1. Sphinx 紹介
Sphinx
reSTreSTreStructuredText
(reST)reST
Parser
HTML Builder
ePub Builder
LaTeX Builder texlive
HTMLtheme
Favorite Editor
Sphinx
生成変換3 4
reSTreSTreStructuredText記法
原稿
読込2
好きなエディタで原稿を書く1
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 紹介
Sphinxの父メンテナンスが大変
~2007
書きやすくメンテナンスしやすい2007~
Sphinx 以前、 Sphinx 以降Sphinx 以前ドキュメントを書く標準的な方法がなかった出力フォーマットに合わせて、一度書いたドキュメントを変換する必要があったSphinx 以降1つのソースから複数フォーマットのドキュメントを生成同梱の 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 / accepted at 2002)
18
1. Sphinx 紹介
Sphinx
reST Parser
HTML Builder
ePub Builder
LaTeX Builder
HTMLtheme
docutils
Docutils と Sphinx の機能比較Docutils Sphinx1. 単一ページ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 紹介
2. Sphinx と 他のツールとの比較
20
ドキュメントを書くのに、何を使用していますか?ワープロソフト
Word一太郎OpenOffice Writer
2. Sphinx と他のツールとの比較
Microsoft の Office のテンプレートのサイトより転載21
ワープロソフトのメリット縦書きで編集できる文法チェックしてくれる差分比較機能がある参考文献、索引、差し込み印刷 etc…
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
Microsoft の Office のテンプレートのサイトより転載22
ワープロソフトのデメリット巨大な 1 ファイルになる探すのが大変複数人で編集が大変章の入れ替えとか厳しい
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
Microsoft の Office のテンプレートのサイトより転載23
ドキュメントを書くのに、何を使用していますか?表計算
ExcelCalc
2. Sphinx と他のツールとの比較
Microsoft の Office のテンプレートのサイトより転載24
表計算のメリットExcel扱える人は多いぱっと作るのは早くできるロジカルシンキング的に苦心しなくても、罫線で武装すると、見た目が立派に見える
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
Microsoft の Office のテンプレートのサイトより転載25
表計算のデメリットワークシートで分断され、閲覧性が悪い内容の追加でレイアウトの修正が必要になると、修正に膨大な時間がかかる
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
Microsoft の Office のテンプレートのサイトより転載26
ドキュメントを書くのに、何を使用していますか?それ以外
WikiHTML手書きTeXMarkdown
2. Sphinx と他のツールとの比較
27
Wiki のメリット圧倒的に柔軟
構造化されていなくても、とりあえず入れておける複数人での編集・閲覧ができる
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
28
Wiki のデメリット文章の構成、質の維持に目を光らせる必要がある
あるいは、 Wikipedia のように構成を決めておく全体の構成を修正するのに手間がかかるトップダウン型ではないので、まとめて印刷や他形式に変換がやりにくい
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
29
Markdown のメリット書きやすくて読みやすいプレーンテキストとして記述した文書バージョンコントロール OK !覚えるべき文法が少ないいざとなったら HTML タグで書ける本家Markdown 以外の文法(フレーバー)を使えば表現の幅が広がるWYSIWIG エディタがある
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
30
Markdown のデメリットMarkdown 文法で表現できる範囲が狭いファイルをまたがった参照などがない出力フォーマットは(基本) HTML のみ文法に拡張性が無いため、各種フレーバーが乱立、それぞれに互換性がない
CommonMark, GitHub-flavored, PHP Markdown Extra, ...
単一ページしか扱えないJekyll という Markdown を複数ページで扱うツールがあるMarkdown <-> reStructuredText(docutils)Jekyll <-> Sphinx
2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか?
31
Demo
Sphinx のメリット書きやすくて読みやすいプレーンテキストとして記述した文書バージョンコントロール OK !ドキュメントの背骨がしっかりさせる複数ページで構成された大きな文章を扱える有機的に文章を繋げる仕組みを持っている
クロスリファレンス , ドメイン , 用語集 , 索引 , ...複数のフォーマットに出力できる
2. Sphinx と他のツールとの比較
http://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird
32
Demo
Sphinx のデメリット背骨を気にして、コンテンツを追加する必要reStructuredText マークアップを覚える(多い)WYSIWIG エディタがない拡張を駆使したドキュメントはメンテしづらい
始めるときのハードルが高い
2. Sphinx と他のツールとの比較
http://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird
33
3. Sphinx インストール
34
$ pip install sphinx
Sphinx のインストール1. Python をインストール (OS による )2. Sphinx本体をインストール
35
3. Sphinx インストール
Python のバージョンに注意して下さいSphinx は Python-3 でも動作します
いくつかの拡張は Python-2 でしか動作しない場合があります。今後、 Python-3 でしか動作しない拡張も増えていくかも?
Demo
Sphinx project の雛形を生成$ cd /path/to/your-doc$ sphinx-quickstart...Project name: Deep thoughtAuthor name(s): MiceProject version: 0.7.5......Finished
36
3. Sphinx インストール
とりあえず 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
3. Sphinx インストール
ドキュメントソース
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)
1
3
原稿の作成と設定 2
sphinx-quickstart から HTML 生成まで3. Sphinx インストール
38
$ make html...Build finished. The HTML pages are in _build/html.
"make html" コマンドで _build/html ディレクトリ以下にhtml ファイルが生成されます
最初の make html
39
3. Sphinx インストール Demo
4. Sphinx の拡張
40
Sphinx の拡張Sphinx は拡張 (extension) を追加できます。いくつかの拡張は built-in として内蔵しており、だれでも拡張を作ったり、誰かが公開している拡張を自由に利用できます。読み込みの拡張文法の拡張ビルダーの拡張HTML テーマの拡張
41
4. Sphinx の拡張
Sphinx
reST Parser
HTML Builder
ePub Builder
LaTeX Builder
docutils
読込の拡
張文法
の拡張
ビルダーの拡張
HTML テーマの拡張
SPHINXdocutils
reSTreSTreStructuredText(reST)
reS
T P
arse
r (d
irect
ive
/ rol
e)
Sph
inx
拡張di
rect
ive
/ rol
e
* 好きなエディタで 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
多言語化S
phin
x拡張
dire
ctiv
e / r
ole
* 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
翻訳者
5. Sphinx の情報源
50
さまざまな情報源イベント
SphinxConPyCon JPSphinx+翻訳 Hack-a-thonSphinx Tea Night
ネットsphinx, docutilssphinx-users.jp
書籍Sphinx をはじめよう (O'reilly)SoftwareDesign の Sphinx連載 2015年 4月号~他
51
5. Sphinx の情報源
SphinxCon JP 20152012年以降、年に 1回開催。今年は 11月 24日 (火 ) 19時~ 渋谷にて開催
プレゼン 5 つ、 LT4 つくらいHack-a-thon やハンズオンは無し
参加者( 10 人~ 40 人)ドキュメントに関わる人関連ツールに関わる人時々出版関係者
52
5. Sphinx の情報源 - イベント
SphinxCon JP 2014sphinxjp.connpass.com
PyCon JP
53
5. Sphinx の情報源 - イベント
Python の年次イベント。 Sphinx-usres.jpとして参加してイベントを併設しています。pycon.jp/2015/
ポスターセッションスプリント
ハンズオン(有料)
Sphinx+翻訳 Hack-a-thon月 1回開催。週末の午後 (6h)Sphinx や翻訳に興味のある人が集まって、それぞれ自分の課題を進めたり、他の人に色々聞いたり、雑談したり。参加者( 4 人~ 8 人)
Sphinx に興味のある方ドキュメントに興味のある方翻訳に興味のある方
場所 : 東京曙橋か新宿の某社
5. Sphinx の情報源 - イベント
54sphinxjp.connpass.com hack-a-thon
Sphinx Tea Night ( お茶会 )
55
5. Sphinx の情報源 - イベント
月 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
5. Sphinx の情報源 - ネット
Sphinx, docutils本家ドキュメントの翻訳リファレンスを日本語に翻訳してありますSphinx: http://docs.sphinx-users.jp/ 90%翻訳済みDocutils: http://docutils.sphinx-users.jp/ 一部翻訳済み
58
5. Sphinx の情報源 - ネット
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
5. Sphinx の情報源 - 書籍
http://gihyo.jp/magazine/SD/archive/2015/201504
エキ Py / PyPro1, 2いくつかの Python の本に、 Sphinx を扱った章があります。コラムで触れている本も含めるともう何冊かありそう
61
5. Sphinx の情報源 - 書籍
PyPro 1 エキ Py
2012年 2010年
PyPro 2
2015年
まとめSphinx は
インストールが簡単設定も簡単書くのも簡単ビルドも簡単カスタマイズもできる拡張もできるサイトも作れるという素晴らしいドキュメントツールだった!
62
Questions?@shimizukawa
63
6. Sphinx デモ
64
Demo コンテンツsphinx-quickstartmake html言語を日本語に変更html テーマ変更make latexpdfjamake epub
65
Sphinx ハンズオン
66
成長のポイント背骨
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
top related