Más contenido relacionado La actualidad más candente (20) Similar a JUS関西 Sphinxワークショップ@関西 Sphinx紹介 (20) Más de Takayuki Shimizukawa (20) JUS関西 Sphinxワークショップ@関西 Sphinx紹介5. Sphinx is 何?
Sphinx はドキュメンテーションジェネレー
タです
SphinxはreSTマークアップから複数の
フォーマットのドキュメントを生成します
5
1. Sphinx紹介
Sphinx
reSTreSTreStructuredText
(reST) reST Parser
HTML Builder
ePub Builder
LaTeX Builder texlive
HTML
theme
Favorite Editor
7. reSTによるドキュメント作成
reST = reStructuredText
http://docs.sphinx-users.jp/rest.html
テキストでも見やすい形
見出し
コードブロック(ハイライト付き)
文書内/文書外リンク
表
toctreeなどを作成する
ファイル間を繋ぐ「背骨」です(後述)
1. Sphinx紹介
============
大見出し
============
中見出し
=========
小見出し
-------------
-リストアイテム1
-リストアイテム2
#. 自動採番アイテム1
#. 自動採番アイテム2
7
Demo
16. 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紹介
17. 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紹介
19. 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紹介
31. Markdownのデメリット
Markdown文法で表現できる範囲が狭い
ファイルをまたがった参照などがない
出力フォーマットは(基本)HTMLのみ
文法に拡張性が無いため、各種フレーバーが乱
立、それぞれに互換性がない
CommonMark, GitHub-flavored, PHP Markdown
Extra, ...
単一ページしか扱えない
Jekyll という Markdownを複数ページで扱うツールが
ある
Markdown <-> reStructuredText(docutils)
Jekyll <-> Sphinx
2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています
か?
31
Demo
35. $ pip install sphinx
Sphinxのインストール
1. Pythonをインストール(OSによる)
2. Sphinx本体をインストール
35
3. Sphinxインストール
Pythonのバージョンに注意して下さい
SphinxはPython-3でも動作します
いくつかの拡張はPython-2でしか動作しない場合があ
ります。
今後、Python-3でしか動作しない拡張も増えていくか
も?
Demo
36. Sphinx projectの雛形を生成
$ cd /path/to/your-doc
$ sphinx-quickstart
...
Project name: Deep thought
Author name(s): Mice
Project version: 0.7.5
...
...
Finished
36
3. Sphinxインストール
とりあえずEnter押しておこう
-q オプションで非対話モード
• "-q" といくつかのオプションを指定すると、対話モード
ではなくすぐに雛形が生成されます。
• Sphinx-1.5から"-m" オプションが標準に。Makefileがシ
ンプルになります。
Demo
37. ファイルの一覧と & 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
39. $ make html
...
Build finished. The HTML pages are in _build/html.
"make html" コマンドで
_build/html ディレクト
リ以下にhtmlファイル
が生成されます
最初のmake html
39
3. Sphinxインストール
Demo
42. SPHINX
docutils
reSTreSTreStructuredText
(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
45. 組み込みのSphinx拡張
todo – Todoアイテムのサポート
autodoc – docstring からの読み込み
intersphinx – 他のSphinxドキュメントへのリンク
pngmath – 数式をPNG画像にレンダリング
jsmath – JavaScriptを用いて数式をレンダリング
graphviz – Graphvizのグラフを追加
coverage – ドキュメントのカバレッジ状況の収集
他にも多くの組み込みSphinx拡張あり
4. Sphinxの拡張
45
Demo
51. さまざまな情報源
イベント
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の情報源
52. SphinxCon JP 2015
2012年以降、年に1回開催。
今年は 11月24日(火) 19時~ 渋谷にて開催
プレゼン5つ、LT4つくらい
Hack-a-thonや
ハンズオンは無し
参加者(10人~40人)
ドキュメントに関わる人
関連ツールに関わる人
時々出版関係者
52
5. Sphinxの情報源 - イベント
SphinxCon JP 2014
sphinxjp.connpass.com
53. PyCon JP
53
5. Sphinxの情報源 - イベント
Pythonの年次イベント。Sphinx-usres.jp
として参加してイベントを併設しています。pycon.jp/2015/
ポスターセッション
スプリント
ハンズオン(有料)
54. Sphinx+翻訳 Hack-a-thon
月1回開催。週末の午後 (6h)
Sphinxや翻訳に興味のある人が集まって、それぞれ
自分の課題を進めたり、他の人に色々聞いたり、雑
談したり。
参加者(4人~8人)
Sphinxに興味のある方
ドキュメントに興味のある方
翻訳に興味のある方
場所: 東京曙橋か新宿の某社
5. Sphinxの情報源 - イベント
54
sphinxjp.connpass.com
hack-a-thon
55. Sphinx Tea Night (お茶会)
55
5. Sphinxの情報源 - イベント
月1回開催。平日の夜 (2h)
Sphinxや翻訳に興味のある人が集まって、雑談して
ます。
参加者(3人~6人)
Sphinxに興味のある方
ドキュメントに興味のある方
なんとなく雑談したい方
場所: 東京市ヶ谷のデニーズ
Tea Night
59. Sphinxをはじめよう(O'Reilly 2013)
Sphinx のみを扱った電子書籍
紙の本で100ページ相当
Sphinxのインストールから、HTML, PDF, EPUBの出
力方法について、reSTの記法について。
付録に、よく使うreST
の文法を掲載
Sphinxを始める人、
必携の書!
59
5. Sphinxの情報源 - 書籍
http://www.oreilly.co.jp/books/9784873116488/
60. 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
61. エキPy / PyPro1, 2
いくつかのPythonの本に、Sphinxを扱った章があり
ます。
コラムで触れている本も含めるともう何冊かありそ
う
61
5. Sphinxの情報源 - 書籍
PyPro 1 エキPy
2012年 2010年
PyPro 2
2015年
68. 背骨の肝:セクションタイトル
ドキュメントを構成する重要な要素
#, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う
自分なりのルールを決めておくと良い
単体のソース内の登場順でH1, H2, H3..が決まる
文字長よりも短いと警告が出ます
========
はじめに
========
想定読者
========
新人社会人
----------
はじめに
想定読者
新人社会人
68
Notas del editor 伝統の「おまえ誰よ」から。
清水川です。
オープンソースで3つの活動をしています。
1. Sphinx co-maintainer since the end of 2011.
2. organize Sphinx-users.jp users group in Japan.
3. member of PyCon JP Committee.
BePROUDで働いています。
弊社では、主にDjangoやPyramidなどを使ってWebアプリケーション開発を行っています。
最近、Pythonトレーニング事業、Python技術サポート事業も始めました。
自宅勤務が週5日までOK、スタンディングデスクあり、ラジオ体操ありの会社です。
それでは、始めましょう。
まずはSphinxの紹介と、Sphinxの多言語対応向けセットアップからです。 Sphinx is 何?
Sphinxはドキュメンテーションジェネレータです。
SphinxはreStructuredTextというテキストマークアップから、複数の出力フォーマットに変換します。
(ポインタでinputとoutputを指す)
Step1 Sphinxの初期ドキュメントから始める
初期ドキュメントから始めると言っても、 “sphinx-quickstart” コマンドで作成しただけの状態のファイルを共有しても、それではドキュメントを書いてくれないでしょう。これは「どう書いて良いか分からない」を解消していません。 Step2 ドキュメントの最初のアウトプットを作成
前述の、読者のターゲット別に章節の構成をおおまかに用意します。この段階でドキュメントの大枠は用意できました。そして、いつでもドキュメントを作成、変更、HTML出力まで動作するようになりました。しかしもう一歩踏み込んで、既に分かっている情報を書いてしまいましょう。 Step3 既に分かっている情報を書き足します。
マネージャー、設計者、開発者それぞれに必要となる情報を用意します。ここまでの情報がそろっていれば、プロジェクト開始時にメンバーに情報が行き渡らないということはあまりなくなると思います。
Step4 段階的にドキュメントに記載していくことで、ドキュメントが成長していきます。
記載していく途中途中で、章の構成もどんどん変わっていってかまいません。このサンプルでは開発プログラムの中心となる2つのライブラリのために独立した章を追加しました。
Tips
対象読者と話の焦点を常に意識する
読者が異なる場合や焦点が異なる場合は適切なページに記載する、リンクする
ホワイトボードに記載したことはデジカメで撮って画像にする。図の清書は必要になるまで不要。
新しい専門用語が出てきたら、都度glossaryとして記載する
専門用語を使うときはglossaryへのリンクとなるようマークアップする
最終ドキュメントに含めない予定のメモも全てreStructuredTextで書きAppendixに入れておく
Appendixの内容はぶら下げる先ができたら移動するなど、時々整理します
Sphinxの歴史をちょっとだけ紹介します。
この人がSphinxの父、Georg Brandlさんです。
PyCon JP 2013のキーノートスピーカーでした。
(クリック)
2007年まで、Pythonの公式ドキュメントはLaTeXで書かれていました。
しかし、これはメンテナンスが難しくて、ほぼ不可能。
Georgはこの状況を変えようとしました。
(クリック)
そして、2007年にSphinxを作りました。
Sphinxは書きやすくてメンテナンスしやすいことを目標に作られました。
Sphinx以前、以降
以前
Python界にはドキュメントを書く標準的な作法が確立していなかった。Python公式ドキュメントもそのうちのひとつで、ドキュメントはLaTeXでかかれていて、LaTeXに変換したりLaTeXから変換する多くのスクリプトジャングルがありました。その頃は、出力フォーマット別に、それらのジャングルスクリプトでマークアップを変換して、さらに別のツールで出力していました。
Sphinxがこの地に降りたって以降、* Python界の住人は、1つのソースコードから複数のフォーマットに出力できるようになりました。
* また、同梱されたHTMLテーマによって、ドキュメントは読みやすくなりました。
* APIリファレンスはライブラリの説明的ドキュメントと1つに統合して出力できるようになりました
* ReadTheDocsという自動ドキュメントビルド&ホスティングサービスが登場し、便利になりました 今では、Sphinxは多くのPythonライブラリで使われるドキュメンテーションツールになりました。
Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …
そしてPython以外のlibrary/toolsでもSphinxは使われています: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
今では、Sphinxは多くのPythonライブラリで使われるドキュメンテーションツールになりました。
Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …
そしてPython以外のlibrary/toolsでもSphinxは使われています: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
Relation between Sphinx and Docutils.
Sphinx is created in 2007 based upon Docutils library.
Docutils and Sphinx supports reStructuredText it called reST, it's an extensible markup. Comparing Docutils and Sphinx. OK, I'll read it.
1. D: handle Single page.
1. S: can handle multiple pages.
2. D: can link to others with full name include ext as like as '.html'.2. S: can connect all pages under single tree structure by using toctree.
3. D: can make Cross reference in a page3. S: can make cross reference over each other pages (without a extension).
4. D: provides writers: html, latex, man, xml, ...4. S: will provide additional writers: html(w/ themes), pdf(latex), texinfo, epub, …
5. D: can handle standard reST markup specs
5. S: will provide additional markup specs: autodoc directive and so on
読込の拡張: autodocなどソースコードからドキュメントを抜き出して自動生成する仕組み
文法の拡張: Sphinxドキュメント内にgraphvizなどでグラフを書いたりなど、別の文法を解釈する仕組み
ビルダーの拡張: 出力フォーマットを増やす仕組み
HTMLテーマ拡張: HTMLのデザインを切り換える仕組み Jinja2 http://jinja.pocoo.org/templates/
Sphinx-User.jp 「テンプレートを作成する」 http://sphinx-users.jp/cookbook/makingwebsite/template.html
Sphinxドメインについて(日本語訳) http://sphinx-users.jp/doc10/domains.html#domains
ドメインのレポジトリ sphinx-contrib http://bitbucket.org/birkenfeld/sphinx-contrib/
組み込みのSphinx拡張 http://sphinx-users.jp/doc10/extensions.html#id1 ドキュメント本家 http://tk0miya.bitbucket.org/blockdiag/build/html/index.html
デモサイト http://blockdiag.appspot.com/ ドキュメント本家 http://tk0miya.bitbucket.org/blockdiag/build/html/index.html
デモサイト http://blockdiag.appspot.com/