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

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

生成変換３４

reSTreSTreStructuredText記法

原稿

読込２

好きなエディタで原稿を書く１

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 / 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


Microsoft の Office のテンプレートのサイトより転載21

ワープロソフトのメリット縦書きで編集できる文法チェックしてくれる差分比較機能がある参考文献、索引、差し込み印刷 etc…

2. Sphinx と他のツールとの比較 - ドキュメントを書くのに、何を使用していますか？


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



ドキュメントを書くのに、何を使用していますか？表計算

ExcelCalc



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



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



ドキュメントを書くのに、何を使用していますか？それ以外

WikiHTML手書きTeXMarkdown


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/4472408386/ CC BY-SA by sweet_redbird

32

Demo

Sphinx のデメリット背骨を気にして、コンテンツを追加する必要reStructuredText マークアップを覚える（多い）WYSIWIG エディタがない拡張を駆使したドキュメントはメンテしづらい

始めるときのハードルが高い


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


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


とりあえず 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 生成まで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 2015２０１２年以降、年に 1回開催。今年は 11月 24日 (火 ) 19時～渋谷にて開催

プレゼン 5 つ、 LT4 つくらいHack-a-thon やハンズオンは無し

参加者（ 10 人～ 40 人）ドキュメントに関わる人関連ツールに関わる人時々出版関係者

52

5. Sphinx の情報源 - イベント

SphinxCon JP 2014sphinxjp.connpass.com

PyCon JP

53


Python の年次イベント。 Sphinx-usres.jpとして参加してイベントを併設しています。pycon.jp/2015/

ポスターセッションスプリント

ハンズオン（有料）

Sphinx+翻訳 Hack-a-thon月 1回開催。週末の午後 (6h)Sphinx や翻訳に興味のある人が集まって、それぞれ自分の課題を進めたり、他の人に色々聞いたり、雑談したり。参加者（ 4 人～ 8 人）

Sphinx に興味のある方ドキュメントに興味のある方翻訳に興味のある方

場所 : 東京曙橋か新宿の某社


54sphinxjp.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/英語です

http://sphinx-doc.org/

http://docutils.sourceforge.net/

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


http://docs.sphinx-users.jp/



http://docutils.sphinx-users.jp/

http://docutils.sphinx-users.jp/

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

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

Technology

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