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

Web Developer at BePROUD Inc.
Oct. 31, 2015
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
1 of 71

More Related Content

What's hot

ドキュメントシステムはこれを使え2015年版ドキュメントシステムはこれを使え2015年版
ドキュメントシステムはこれを使え2015年版Keiichiro Shikano
Sphinx ではじめるドキュメント生活 2013 #sphinxconjpSphinx ではじめるドキュメント生活 2013 #sphinxconjp
Sphinx ではじめるドキュメント生活 2013 #sphinxconjpTakeshi Komiya
SIerでもSphinxを使いたい! 前編SIerでもSphinxを使いたい! 前編
SIerでもSphinxを使いたい! 前編kk_Ataka
BPstudy#64 ドキュメントを作りたくなってしまう魔法のツール Sphinx 2012年版BPstudy#64 ドキュメントを作りたくなってしまう魔法のツール Sphinx 2012年版
BPstudy#64 ドキュメントを作りたくなってしまう魔法のツール Sphinx 2012年版Go Yamada
Oktavia全文検索エンジン - SphinxCon JP 2014Oktavia全文検索エンジン - SphinxCon JP 2014
Oktavia全文検索エンジン - SphinxCon JP 2014Yoshiki Shibukawa
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjpSphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjpTakeshi Komiya

What's hot(20)

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

Sphinxでドキュメントを書こうSphinxでドキュメントを書こう
Sphinxでドキュメントを書こうKazufumi Ohkawa
ドキュメントの継続的改善―Sphinxを使いながらドキュメントの継続的改善―Sphinxを使いながら
ドキュメントの継続的改善―Sphinxを使いながらsoishino
Tinkerer for pyfes 201303Tinkerer for pyfes 201303
Tinkerer for pyfes 201303shirou wakayama
SphinxのCIの続き Azure DevOpsでのビルド結果を、認証付きAzure App Serviceに公開するところまでSphinxのCIの続き Azure DevOpsでのビルド結果を、認証付きAzure App Serviceに公開するところまで
SphinxのCIの続き Azure DevOpsでのビルド結果を、認証付きAzure App Serviceに公開するところまでStudy Group by SciencePark Corp.
Sphinx/reSTSphinx/reST
Sphinx/reSTRyo Maruyama
JSUG 2018/02/05 SpringOnePlatform2017参加報告 プラットフォーム関連のお話JSUG 2018/02/05 SpringOnePlatform2017参加報告 プラットフォーム関連のお話
JSUG 2018/02/05 SpringOnePlatform2017参加報告 プラットフォーム関連のお話Yahoo!デベロッパーネットワーク

Similar to JUS関西 Sphinxワークショップ@関西 Sphinx紹介(20)

More from Takayuki Shimizukawa

OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022Takayuki Shimizukawa
Webアプリを並行開発する際のマイグレーション戦略Webアプリを並行開発する際のマイグレーション戦略
Webアプリを並行開発する際のマイグレーション戦略Takayuki Shimizukawa
『自走プログラマー』 が我々に必要だった理由『自走プログラマー』 が我々に必要だった理由
『自走プログラマー』 が我々に必要だった理由Takayuki Shimizukawa
エキスパートPythonプログラミング改訂3版の読みどころエキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころTakayuki Shimizukawa
RLSを用いたマルチテナント実装 for DjangoRLSを用いたマルチテナント実装 for Django
RLSを用いたマルチテナント実装 for DjangoTakayuki Shimizukawa
独学プログラマーのその後独学プログラマーのその後
独学プログラマーのその後Takayuki Shimizukawa

More from Takayuki Shimizukawa(20)

Recently uploaded

ヒアラブルデバイスにおける音漏れ信号を用いた空中ジェスチャ認識ヒアラブルデバイスにおける音漏れ信号を用いた空中ジェスチャ認識
ヒアラブルデバイスにおける音漏れ信号を用いた空中ジェスチャ認識sugiuralab
磁石内臓イヤリングによる磁力変化を利用したジェスチャ識別磁石内臓イヤリングによる磁力変化を利用したジェスチャ識別
磁石内臓イヤリングによる磁力変化を利用したジェスチャ識別sugiuralab
PostgreSQLのバグとの付き合い方 ~バグの調査からコミュニティへの報告、修正パッチ投稿まで~(Open Source Conference 202...PostgreSQLのバグとの付き合い方 ~バグの調査からコミュニティへの報告、修正パッチ投稿まで~(Open Source Conference 202...
PostgreSQLのバグとの付き合い方 ~バグの調査からコミュニティへの報告、修正パッチ投稿まで~(Open Source Conference 202...NTT DATA Technology & Innovation
インフラチームとCCoEの関係.pptxインフラチームとCCoEの関係.pptx
インフラチームとCCoEの関係.pptxssuser5c7ee4
CatBoost on GPU のひみつCatBoost on GPU のひみつ
CatBoost on GPU のひみつTakuji Tahara
GraphQLはどんな時に使うかGraphQLはどんな時に使うか
GraphQLはどんな時に使うかYutaka Tachibana

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

Editor's Notes

  1. 伝統の「おまえ誰よ」から。 清水川です。 オープンソースで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、スタンディングデスクあり、ラジオ体操ありの会社です。
  2. それでは、始めましょう。 まずはSphinxの紹介と、Sphinxの多言語対応向けセットアップからです。
  3. Sphinx is 何? Sphinxはドキュメンテーションジェネレータです。 SphinxはreStructuredTextというテキストマークアップから、複数の出力フォーマットに変換します。 (ポインタでinputとoutputを指す)
  4. Step1 Sphinxの初期ドキュメントから始める 初期ドキュメントから始めると言っても、 “sphinx-quickstart” コマンドで作成しただけの状態のファイルを共有しても、それではドキュメントを書いてくれないでしょう。これは「どう書いて良いか分からない」を解消していません。
  5. Step2 ドキュメントの最初のアウトプットを作成 前述の、読者のターゲット別に章節の構成をおおまかに用意します。この段階でドキュメントの大枠は用意できました。そして、いつでもドキュメントを作成、変更、HTML出力まで動作するようになりました。しかしもう一歩踏み込んで、既に分かっている情報を書いてしまいましょう。
  6. Step3 既に分かっている情報を書き足します。 マネージャー、設計者、開発者それぞれに必要となる情報を用意します。ここまでの情報がそろっていれば、プロジェクト開始時にメンバーに情報が行き渡らないということはあまりなくなると思います。
  7. Step4 段階的にドキュメントに記載していくことで、ドキュメントが成長していきます。 記載していく途中途中で、章の構成もどんどん変わっていってかまいません。このサンプルでは開発プログラムの中心となる2つのライブラリのために独立した章を追加しました。 Tips 対象読者と話の焦点を常に意識する 読者が異なる場合や焦点が異なる場合は適切なページに記載する、リンクする ホワイトボードに記載したことはデジカメで撮って画像にする。図の清書は必要になるまで不要。 新しい専門用語が出てきたら、都度glossaryとして記載する 専門用語を使うときはglossaryへのリンクとなるようマークアップする 最終ドキュメントに含めない予定のメモも全てreStructuredTextで書きAppendixに入れておく Appendixの内容はぶら下げる先ができたら移動するなど、時々整理します
  8. Sphinxの歴史をちょっとだけ紹介します。 この人がSphinxの父、Georg Brandlさんです。 PyCon JP 2013のキーノートスピーカーでした。 (クリック) 2007年まで、Pythonの公式ドキュメントはLaTeXで書かれていました。 しかし、これはメンテナンスが難しくて、ほぼ不可能。 Georgはこの状況を変えようとしました。 (クリック) そして、2007年にSphinxを作りました。 Sphinxは書きやすくてメンテナンスしやすいことを目標に作られました。
  9. Sphinx以前、以降 以前 Python界にはドキュメントを書く標準的な作法が確立していなかった。Python公式ドキュメントもそのうちのひとつで、ドキュメントはLaTeXでかかれていて、LaTeXに変換したりLaTeXから変換する多くのスクリプトジャングルがありました。その頃は、出力フォーマット別に、それらのジャングルスクリプトでマークアップを変換して、さらに別のツールで出力していました。 Sphinxがこの地に降りたって以降、 * Python界の住人は、1つのソースコードから複数のフォーマットに出力できるようになりました。 * また、同梱されたHTMLテーマによって、ドキュメントは読みやすくなりました。 * APIリファレンスはライブラリの説明的ドキュメントと1つに統合して出力できるようになりました * ReadTheDocsという自動ドキュメントビルド&ホスティングサービスが登場し、便利になりました
  10. 今では、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
  11. 今では、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
  12. 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.
  13. 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
  14. 読込の拡張: autodocなどソースコードからドキュメントを抜き出して自動生成する仕組み 文法の拡張: Sphinxドキュメント内にgraphvizなどでグラフを書いたりなど、別の文法を解釈する仕組み ビルダーの拡張: 出力フォーマットを増やす仕組み HTMLテーマ拡張: HTMLのデザインを切り換える仕組み
  15. Jinja2 http://jinja.pocoo.org/templates/ Sphinx-User.jp 「テンプレートを作成する」 http://sphinx-users.jp/cookbook/makingwebsite/template.html
  16. Sphinxドメインについて(日本語訳) http://sphinx-users.jp/doc10/domains.html#domains ドメインのレポジトリ sphinx-contrib http://bitbucket.org/birkenfeld/sphinx-contrib/
  17. 組み込みのSphinx拡張 http://sphinx-users.jp/doc10/extensions.html#id1
  18. ドキュメント本家 http://tk0miya.bitbucket.org/blockdiag/build/html/index.html デモサイト http://blockdiag.appspot.com/
  19. ドキュメント本家 http://tk0miya.bitbucket.org/blockdiag/build/html/index.html デモサイト http://blockdiag.appspot.com/