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

3,077 views

Published on

Sphinxの紹介

Published in: Technology
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,077
On SlideShare
0
From Embeds
0
Number of Embeds
1,986
Actions
Shares
0
Downloads
5
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide
  • 伝統の「おまえ誰よ」から。

    清水川です。
    オープンソースで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 page 3. 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/
  • JUS関西 Sphinxワークショップ@関西 Sphinx紹介

    1. 1. 1 Takayuki Shimizukawa Sphinx co-maintainer Sphinx-users.jp
    2. 2. おまえ誰よ @shimizukawa(清水川)  Sphinx メンテナ  Sphinx-users.jp  一般社団法人PyCon JP 理事  Python mini hack-a-thon運営 2
    3. 3. アジェンダ 1. Sphinx概要紹介 2. Sphinxと他のツールを比較 3. Sphinxインストール 4. Sphinx拡張紹介 5. Sphinxの情報源 6. Sphinxデモ 3
    4. 4. 4
    5. 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. 6. Sphinx 生成変換 3 4 reSTreSTreStructuredText 記法 原稿 読込 2 好きなエディタで原 稿を書く 1 Sphinxドキュメントのおおまかな作成フロー 1. Sphinx紹介 6
    7. 7. reSTによるドキュメント作成  reST = reStructuredText  http://docs.sphinx-users.jp/rest.html  テキストでも見やすい形  見出し  コードブロック(ハイライト付き)  文書内/文書外リンク  表  toctreeなどを作成する  ファイル間を繋ぐ「背骨」です(後述) 1. Sphinx紹介 ============ 大見出し ============ 中見出し ========= 小見出し ------------- -リストアイテム1 -リストアイテム2 #. 自動採番アイテム1 #. 自動採番アイテム2 7 Demo
    8. 8. Step1: Sphinxの初期ドキュメントから始める C:> sphinx-quickstart 1. Sphinx紹介 8
    9. 9. Step2: ドキュメントの最初のアウトプットを作成  読者のターゲット別に章節の構成をおおまかに用意 1. Sphinx紹介 9
    10. 10. Step3: 既に分かっている情報を追加  マネージャー、設計者、開発者それぞれに必要とな る、 プロジェクト特有の情報を記載 1. Sphinx紹介 10
    11. 11. Step4: 段階的にドキュメントに記載 プロジェクトの進捗と共に 成長するドキュメント いつドキュメントを更新する? 1. Sphinx紹介 いつでも! 11
    12. 12. 各種出力  HTML以外にもデフォルトでLaTeX、PDF 、ePubに  HTMLもデフォルトで複数のテーマを使用可 1. Sphinx紹介 $ make latex $ make latexpdfja $ make epub 12 Demo
    13. 13. reST原稿と各種出力 1. Sphinx紹介 13
    14. 14. Sphinxの歴史 (ショートver.) 14 1. Sphinx紹介 Sphinxの 父 メンテナンス が大変 ~2007 書きやすく メンテナンスしやす い2007~
    15. 15. Sphinx 以前、Sphinx以降 Sphinx以前  ドキュメントを書く標準的な方法がなかった  出力フォーマットに合わせて、一度書いたドキュメント を変換する必要があった Sphinx以降  1つのソースから複数フォーマットのドキュメントを生 成  同梱のHTMLテーマ機能で読みやすいドキュメントを提 供  APIリファレンスと説明的ドキュメントが同居できる  自動ビルドとホスティングを提供するReadTheDocsの登 15 1. Sphinx紹介
    16. 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. 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. 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. 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. 20
    21. 21. ドキュメントを書くのに、何を使用していますか?  ワープロソフト  Word  一太郎  OpenOffice Writer 2. Sphinxと他のツールとの比較 MicrosoftのOfficeの テンプレートのサイトより転載 21
    22. 22. ワープロソフトのメリット  縦書きで編集できる  文法チェックしてくれる  差分比較機能がある  参考文献、索引、 差し込み印刷etc… 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? MicrosoftのOfficeの テンプレートのサイトより転載 22
    23. 23. ワープロソフトのデメリット  巨大な1ファイルになる  探すのが大変  複数人で編集が大変  章の入れ替えとか厳しい 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? MicrosoftのOfficeの テンプレートのサイトより転載 23
    24. 24. ドキュメントを書くのに、何を使用していますか?  表計算  Excel  Calc 2. Sphinxと他のツールとの比較 MicrosoftのOfficeの テンプレートのサイトより転載 24
    25. 25. 表計算のメリット  Excel扱える人は多い  ぱっと作るのは早くでき る  ロジカルシンキング的に 苦心しなくても、罫線で 武装すると、見た目が立 派に見える 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? MicrosoftのOfficeの テンプレートのサイトより転載 25
    26. 26. 表計算のデメリット  ワークシートで分断され、 閲覧性が悪い  内容の追加でレイアウト の修正が必要になると、 修正に膨大な時間がかか る 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? MicrosoftのOfficeの テンプレートのサイトより転載 26
    27. 27. ドキュメントを書くのに、何を使用していますか?  それ以外  Wiki  HTML手書き  TeX  Markdown 2. Sphinxと他のツールとの比較 27
    28. 28. Wikiのメリット  圧倒的に柔軟  構造化されていなくても、とりあえず入れてお ける  複数人での編集・閲覧ができる 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? 28
    29. 29. Wikiのデメリット  文章の構成、質の維持に目を光らせる必要がある  あるいは、Wikipediaのように構成を決めておく  全体の構成を修正するのに 手間がかかる  トップダウン型ではないので、 まとめて印刷や他形式に変換 がやりにくい 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? 29
    30. 30. Markdownのメリット  書きやすくて読みやすいプレーンテキストとして記 述した文書  バージョンコントロールOK!  覚えるべき文法が少ない  いざとなったらHTMLタグで書ける  本家Markdown以外の文法(フレーバー)を使えば 表現の幅が広がる  WYSIWIGエディタがある 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? 30
    31. 31. Markdownのデメリット  Markdown文法で表現できる範囲が狭い  ファイルをまたがった参照などがない  出力フォーマットは(基本)HTMLのみ  文法に拡張性が無いため、各種フレーバーが乱 立、それぞれに互換性がない  CommonMark, GitHub-flavored, PHP Markdown Extra, ...  単一ページしか扱えない  Jekyll という Markdownを複数ページで扱うツールが ある  Markdown <-> reStructuredText(docutils)  Jekyll <-> Sphinx 2. Sphinxと他のツールとの比較 -ドキュメントを書くのに、何を使用しています か? 31 Demo
    32. 32. Sphinxのメリット  書きやすくて読みやすいプレーンテキストとして記 述した文書  バージョンコントロールOK!  ドキュメントの背骨がしっかりさせる  複数ページで構成された大きな文章を扱える  有機的に文章を繋げる仕組みを持っている  クロスリファレンス, ドメイン, 用語集, 索引, ...  複数のフォーマットに出力できる 2. Sphinxと他のツールとの比較 http://www.flickr.com/photos/18261299@N00/44724083 86/ CC BY-SA by sweet_redbird 32 Demo
    33. 33. Sphinxのデメリット  背骨を気にして、コンテンツを追加する必要  reStructuredText マークアップを覚える(多い)  WYSIWIGエディタがない  拡張を駆使したドキュメントはメンテしづらい 始めるときのハードルが高い 2. Sphinxと他のツールとの比較 http://www.flickr.com/photos/18261299@N00/44724083 86/ CC BY-SA by sweet_redbird 33
    34. 34. 34
    35. 35. $ pip install sphinx Sphinxのインストール 1. Pythonをインストール(OSによる) 2. Sphinx本体をインストール 35 3. Sphinxインストール  Pythonのバージョンに注意して下さい  SphinxはPython-3でも動作します  いくつかの拡張はPython-2でしか動作しない場合があ ります。  今後、Python-3でしか動作しない拡張も増えていくか も? Demo
    36. 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. 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. 38. reStructuredText (reST) SphinxreStructuredText (reST) reStructuredText (reST) で書いた原稿 プロジェクト HTML生成 (make html) プロジェクトの作成 (sphinx-quickstart) 設定ファイル (conf.py) 1 3 原稿の作成と設定 2 sphinx-quickstart から HTML生成まで 3. Sphinxインストール 38
    39. 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. 40
    41. 41. Sphinxの拡張 Sphinxは拡張(extension)を追加できます。 いくつかの拡張はbuilt-inとして内蔵してお り、だれでも拡張を作ったり、誰かが公開 している拡張を自由に利用できます。  読み込みの拡張  文法の拡張  ビルダーの拡張  HTMLテーマの拡張 41 4. Sphinxの拡張 Sphinx reST Parser HTML Builder ePub Builder LaTeX Builder docutils 読込の拡張 文法の拡張 ビルダーの拡張 HTMLテーマ の拡張
    42. 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. 43. テンプレートの作成  テンプレートエンジン “Jinja2”を利用している  大まかに分けて2つのhtmlを作成する  ドキュメント全体の基礎 : layout.html  各ページ : page.html  デフォルトテーマ basic のテンプレート継承により 時間が削減 4. Sphinxの拡張 自分でテンプレートを作成することも可能 43 Demo
    44. 44. Sphinxドメイン  ある言語を説明するマークアップとSphinx内のオブ ジェクトのリンク  Python以外にも多くの言語に対応&独自に作成可能 (Erlang, Ruby, C++, JavaScript…)  ドキュメント内で相互参照が可能 例) C言語 4. Sphinxの拡張 .. c:function:: int printf(const char *format, …) 44 Demo
    45. 45. 組み込みのSphinx拡張  todo – Todoアイテムのサポート  autodoc – docstring からの読み込み  intersphinx – 他のSphinxドキュメントへのリンク  pngmath – 数式をPNG画像にレンダリング  jsmath – JavaScriptを用いて数式をレンダリング  graphviz – Graphvizのグラフを追加  coverage – ドキュメントのカバレッジ状況の収集 他にも多くの組み込みSphinx拡張あり 4. Sphinxの拡張 45 Demo
    46. 46. サードパーティのSphinx拡張  blockdiagシリーズ  blockdiag: ブロック遷移図を簡単な記述だけで作成  seqdiag: シーケンス図を簡単な記述だけで作成  actdiag, nwdiag, rackdiag, packetdiag 等 4. Sphinxの拡張 46
    47. 47. blockdiag  ブロック遷移図を文字のみで書けます  sphinxcontrib-blockdiag でSphinxでブロック遷移図 を書くことが可能 4. Sphinxの拡張 .. blockdiag:: { A -> B -> C; B -> D; } 47 Demo
    48. 48. seqdiag  シーケンス図を文字のみで書けます  sphinxcontrib-seqdiag でSphinxでシーケンスを書く ことが可能 4. Sphinxの拡張 .. blockdiag:: { browser -> webserver[label=GET]; browser <-- webserver; browser -> WebAPI; } 48
    49. 49. Sphinx i18n機能でのドキュメント翻訳プロセス 49 4. Sphinxの拡張 reST pot html po make gettext sphinx-intl make html ドキュメント作者 翻訳カタログ 翻訳済カタログ 翻訳者 翻訳者 翻訳者 作者 / 翻訳者 アップロード 翻訳者 clone 翻訳者
    50. 50. 50
    51. 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. 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. 53. PyCon JP 53 5. Sphinxの情報源 - イベント  Pythonの年次イベント。Sphinx-usres.jp として参加してイベントを併設しています。pycon.jp/2015/ ポスターセッション スプリント ハンズオン(有料)
    54. 54. Sphinx+翻訳 Hack-a-thon  月1回開催。週末の午後 (6h)  Sphinxや翻訳に興味のある人が集まって、それぞれ 自分の課題を進めたり、他の人に色々聞いたり、雑 談したり。  参加者(4人~8人)  Sphinxに興味のある方  ドキュメントに興味のある方  翻訳に興味のある方  場所: 東京曙橋か新宿の某社 5. Sphinxの情報源 - イベント 54 sphinxjp.connpass.com hack-a-thon
    55. 55. Sphinx Tea Night (お茶会) 55 5. Sphinxの情報源 - イベント  月1回開催。平日の夜 (2h)  Sphinxや翻訳に興味のある人が集まって、雑談して ます。  参加者(3人~6人)  Sphinxに興味のある方  ドキュメントに興味のある方  なんとなく雑談したい方  場所: 東京市ヶ谷のデニーズ Tea Night
    56. 56. Sphinx, docutils本家ドキュメント 56 5. Sphinxの情報源 - ネット  Sphinx本家: http://sphinx-doc.org/  Docutils本家: http://docutils.sourceforge.net/  英語です
    57. 57.  本家ドキュメントにはない、さまざまな情報を複数 の切り口で提供。MLの案内もここに。  サイト自体Sphinxで作っています  Twitter: @sphinxjp #sphinxjp Sphinx-users.jp 57 5. Sphinxの情報源 - ネット
    58. 58. Sphinx, docutils本家ドキュメントの翻訳  リファレンスを日本語に翻訳してあります  Sphinx: http://docs.sphinx-users.jp/ 90%翻訳済み  Docutils: http://docutils.sphinx-users.jp/ 一部翻訳済 み 58 5. Sphinxの情報源 - ネット
    59. 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. 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. 61. エキPy / PyPro1, 2  いくつかのPythonの本に、Sphinxを扱った章があり ます。  コラムで触れている本も含めるともう何冊かありそ う 61 5. Sphinxの情報源 - 書籍 PyPro 1 エキPy 2012年 2010年 PyPro 2 2015年
    62. 62. まとめ  Sphinxは  インストールが簡単  設定も簡単  書くのも簡単  ビルドも簡単  カスタマイズもできる  拡張もできる  サイトも作れる という素晴らしいドキュメントツールだった! 62
    63. 63. Questions? @shimizukawa 63
    64. 64. 64
    65. 65. Demoコンテンツ  sphinx-quickstart  make html  言語を日本語に変更  htmlテーマ変更  make latexpdfja  make epub 65
    66. 66. 66
    67. 67. 成長のポイント  背骨  toctree!toctree!toctree!  神経のネットワーク  セマンティックスを定義していく 67
    68. 68. 背骨の肝:セクションタイトル  ドキュメントを構成する重要な要素  #, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う  自分なりのルールを決めておくと良い  単体のソース内の登場順でH1, H2, H3..が決まる  文字長よりも短いと警告が出ます ======== はじめに ======== 想定読者 ======== 新人社会人 ---------- はじめに 想定読者 新人社会人 68
    69. 69. 背骨の肝:親子関係の定義  Sphinxの一番重要な部分  toctreeディレクティブを使って定義する  拡張子なしのファイル名を列挙する  目次がその場で作られる .. toctree:: :maxdepth: 2 preface overview/index defensive/index  はじめに  本書の考えるゴール  本書を作るにあたって  本書で説明していくこと  つまみぐい勉強法  勉強はつまみぐいから  大切なことは、継続  自分に合うものを選ぼう  終着点は自分で決めよう 69
    70. 70. 背骨の肝:親子関係の定義  セクションタイトルを子供の文書から引っ張ってき て目次を作る  toctree自体は1文書に何個も書ける  toctree表示位置に、子供の文書のセクション構造が 挿入される toctreeができたら、Sphinx黒帯! 70
    71. 71. ドキュメントのモチベーションを上げ  いろんなやる気のスイッチを活用  全体像を見て、足りない項目を補完  とにかく、細かい部分から徹底的に丁寧に  索引を見て、索引を充実させる  読む人ごとの入り口を作ってみる  いろんなフォーマットで出力してみる 71

    ×