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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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紹介

18. 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

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紹介

20. 20

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

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

23. ワープロソフトのデメリット  巨大な1ファイルになる  探すのが大変  複数人で編集が大変  章の入れ替えとか厳しい 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用していますか？ MicrosoftのOfficeのテンプレートのサイトより転載 23

24. ドキュメントを書くのに、何を使用していますか？  表計算  Excel  Calc 2. Sphinxと他のツールとの比較 MicrosoftのOfficeのテンプレートのサイトより転載 24

25. 表計算のメリット  Excel扱える人は多い  ぱっと作るのは早くできる  ロジカルシンキング的に苦心しなくても、罫線で武装すると、見た目が立派に見える 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用していますか？ MicrosoftのOfficeのテンプレートのサイトより転載 25

26. 表計算のデメリット  ワークシートで分断され、閲覧性が悪い  内容の追加でレイアウトの修正が必要になると、修正に膨大な時間がかかる 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用していますか？ MicrosoftのOfficeのテンプレートのサイトより転載 26

27. ドキュメントを書くのに、何を使用していますか？  それ以外  Wiki  HTML手書き  TeX  Markdown 2. Sphinxと他のツールとの比較 27

28. Wikiのメリット  圧倒的に柔軟  構造化されていなくても、とりあえず入れておける  複数人での編集・閲覧ができる 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用していますか？ 28

29. Wikiのデメリット  文章の構成、質の維持に目を光らせる必要がある  あるいは、Wikipediaのように構成を決めておく  全体の構成を修正するのに手間がかかる  トップダウン型ではないので、まとめて印刷や他形式に変換がやりにくい 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用していますか？ 29

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

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

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

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

34. 34

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

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

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

40. 40

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

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

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

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

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

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

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

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

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

50. 50

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  ２０１２年以降、年に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

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

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

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

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年

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

63. Questions? @shimizukawa 63

64. 64

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

66. 66

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

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

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

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

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