Building document
with the Sphinx
2013-09
Public edtion
Wednesday, September 11, 13
この資料?
• チームでアプリケーションつくってます
• APIリファレンスを管理しやすく・見やすく
しよう
• チームメンバ向けにSphinxを紹介した時の
スライドです
• 公開向けに加工しました
• 画像のぼかし
• 字幕
2
Wedne...
2008 Word
3
2008年、プロジェクトのドキュメントはWordで作られていました
この方式の欠点はみなさんご存知のとおりでしょう
Wednesday, September 11, 13
2010 Dokuwiki
4
2010年のプロジェクトではphpのアプリケーションを使いました。
版の管理、手軽さは飛躍的に向上しました、環境の管理が必要でした。
Wednesday, September 11, 13
2012 markdown based
5
2012年にはmarkdownを変換する自作のRubyアプリケーションで
APIリファレンスを提供しました。
Wednesday, September 11, 13
2013 Github pages ?
6
そして2013年、GithubのWikiにリファレンスを書き始めましたが...
Wednesday, September 11, 13
Github Pages are...
• Poor search
• Grow much bigger!!
• kindless to reading
• No indexing
• No relasionship
7
本当にそれでいいのでし...
Lighitweight Documentation
8
http://www.slideshare.net/shimizukawa/blockdiag-jus20116
もっとコラボレーションしやすいものがあるのでは?
Wednesday, ...
2013 Sphinx!!
9
そうだ、Sphinxでいこうよ。
これはGithub wikiのMarkdownを単純に変換したものです。
Wednesday, September 11, 13
The Sphinx
10
• Document Builder
• Python project
• install with pip, easy_install
• (But) Don t need any knowledge of Pyt...
Tool: Pandoc
universal docoment converter
11
ありがとうPandoc
Wednesday, September 11, 13
Getting started
with the Sphinx !!
今夜できる、Sphinx ドキュメンテーション
Wednesday, September 11, 13
sphinx-quickstart
$ sphinx-quickstart
Welcome to the Sphinx 1.2b1 quickstart utility.
Please enter values for the followin...
You have two options for placing the build directory for Sphinx
output.
Either, you use a directory "_build" within the ro...
The project name will occur in several places in the built
documentation.
> Project name: sphinx_sinatra_example
> Author ...
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For exampl...
The file name suffix for source files. Commonly, this is either
".txt"
or ".rst". Only files with this suffix are considered docu...
One document is special in that it is considered the top node of
the
"contents tree", that is, it is the root of the hiera...
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:
19
まだ対話が続くよ、あと2ページほど。
オ...
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from...
A Makefile and a Windows command file can be generated for
you so that you
only have to run e.g. `make html' instead of invo...
$ tree
├── Makefile # document build tasks
├── build # output directory
└── source # reST files directory
├── _static
├── _t...
$ make html
sphinx-build -b html -d build/doctrees source build/html
Making output directory...
Running Sphinx v1.2b1
load...
$ tree build/html/
build/html/
├── _sources
│ └── index.txt
├── _static
│ ├── ajax-loader.gif
│ ├── basic.css
│ ├── commen...
25
open build/html/index.html
私のドキュメントにようこそ
すでにカッコイイじゃないですかー
Wednesday, September 11, 13
write first page
では書きたいことを
書きたいように書いていこう
Wednesday, September 11, 13
add name to index.rst
Contents:
.. toctree::
:maxdepth: 2
27
Contents:
.. toctree::
:maxdepth: 2
public
APIリソースのpublicについて...
write source/public.rst
28
※ convert from markdown by pandoc
markdown版がもうあるので、pandocで変換してみたのがこちらです
Wednesday, September 11...
Rebuild
$ make html
-- snip --
reading sources... [100%] public
-- snip --
writing output... [100%] public
-- snip --
Buil...
open index.html
30
見出しが! 見出しが並んだよ!
ああ、そうだねぼうや。
Wednesday, September 11, 13
mark up
to index
索引があったらいいのに
本みたいに
Wednesday, September 11, 13
add index before content
POST /v1/public/*****************
Resets the hogehoge
32
.. index::
single: public/reset
POST /v1...
build and open
genindex.html
33
自動でリンク付きの索引を?
なんて素晴らしいんだ。
Wednesday, September 11, 13
Search!
検索機能もついてくるといっても、
必要な手続きやコツがあるんじゃないのかい?
Wednesday, September 11, 13
Nothing to do
いいえ、みなさんは何もする必要がありません。
Wednesday, September 11, 13
search for all documents
36
ドキュメントはビルドするだけで、searchの対象なんだ。
※日本語対応してるかを見てない
Wednesday, September 11, 13
Show raw reST file
少しの修正を施したいけど、
reSTの書き方をど忘れしたって?
Wednesday, September 11, 13
38
きっとshow source リンクをクリックするんだ。
Wednesday, September 11, 13
View reST on web browser
39
ほら、reSTファイルだ。
※コンフィグで有効/無効
Wednesday, September 11, 13
Document
Versioning
アプリケーションのバージョンごとに
別のドキュメントにする必要が求められることがある。
Wednesday, September 11, 13
sphinx-build
(Modify Makefile)
Makefileで、ちょちょいのちょいなんだけど
Wednesday, September 11, 13
Modify BUILDDIR
BUILDDIR = build
42
BUILDDIR = build/1.0
他に良いやり方知ってる人教えてください
Wednesday, September 11, 13
$ make html
sphinx-build -b html -d build/1.0/doctrees source build/1.0/
html
-- snip --
Build finished. The HTML pages are...
upgrade
mejour version
このやり方があんまりスマートにも思えないんだ
Wednesday, September 11, 13
conf.py and Makefile
## conf.py
version = '1.1'
release = '1.1'
## Makefile
BUILDDIR = build/1.1
45
conf.pyはいいとしてもね
Wednesda...
example of version selection!
but modify template manually maybe...
46
Pythonの公式サイトみたいにしたいね
Wednesday, September 11, 13
Appendix.1
Dash.app
知ってるかい Dash.app
Wednesday, September 11, 13
Dash.app
48
ローカル本棚だよ
Wednesday, September 11, 13
import from sphinx
49
doc2dashでググれ
Wednesday, September 11, 13
Appendix.2
Publish to heroku
htmlにしたら何処かでホスト必要がある、
herokuに置いてしまう方法を紹介しよう。
Wednesday, September 11, 13
static html publishing with sinatra
http://qiita.com/sawanoboly@github/items/be1dbc9f19e93e4b62cf
51
今じゃないけど。
Wednesday, S...
Thanks
ありがとう
Wednesday, September 11, 13
Upcoming SlideShare
Loading in...5
×

Building document with the Sphinx public edtion

906

Published on

某社で社内向けにsphinxを紹介した時のスライドです。

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

No Downloads
Views
Total Views
906
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
6
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

Building document with the Sphinx public edtion

  1. 1. Building document with the Sphinx 2013-09 Public edtion Wednesday, September 11, 13
  2. 2. この資料? • チームでアプリケーションつくってます • APIリファレンスを管理しやすく・見やすく しよう • チームメンバ向けにSphinxを紹介した時の スライドです • 公開向けに加工しました • 画像のぼかし • 字幕 2 Wednesday, September 11, 13
  3. 3. 2008 Word 3 2008年、プロジェクトのドキュメントはWordで作られていました この方式の欠点はみなさんご存知のとおりでしょう Wednesday, September 11, 13
  4. 4. 2010 Dokuwiki 4 2010年のプロジェクトではphpのアプリケーションを使いました。 版の管理、手軽さは飛躍的に向上しました、環境の管理が必要でした。 Wednesday, September 11, 13
  5. 5. 2012 markdown based 5 2012年にはmarkdownを変換する自作のRubyアプリケーションで APIリファレンスを提供しました。 Wednesday, September 11, 13
  6. 6. 2013 Github pages ? 6 そして2013年、GithubのWikiにリファレンスを書き始めましたが... Wednesday, September 11, 13
  7. 7. Github Pages are... • Poor search • Grow much bigger!! • kindless to reading • No indexing • No relasionship 7 本当にそれでいいのでしょうか、いいえ Wednesday, September 11, 13
  8. 8. Lighitweight Documentation 8 http://www.slideshare.net/shimizukawa/blockdiag-jus20116 もっとコラボレーションしやすいものがあるのでは? Wednesday, September 11, 13
  9. 9. 2013 Sphinx!! 9 そうだ、Sphinxでいこうよ。 これはGithub wikiのMarkdownを単純に変換したものです。 Wednesday, September 11, 13
  10. 10. The Sphinx 10 • Document Builder • Python project • install with pip, easy_install • (But) Don t need any knowledge of Python. • Write once publish anywere.(with pahdoc) • write reST (reStructuredText) or Markdown • to html, epub, man, TeX, etc... たぶんすばらしいSphinxの世界 Wednesday, September 11, 13
  11. 11. Tool: Pandoc universal docoment converter 11 ありがとうPandoc Wednesday, September 11, 13
  12. 12. Getting started with the Sphinx !! 今夜できる、Sphinx ドキュメンテーション Wednesday, September 11, 13
  13. 13. sphinx-quickstart $ sphinx-quickstart Welcome to the Sphinx 1.2b1 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: 13 簡単スタートツール、sphinx-quickstartとの対話を フルコーラスでご覧ください Wednesday, September 11, 13
  14. 14. You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/N) [n]: y 14 赤い所が入力箇所! といっても、ほとんど入力する必要は無いんだけどね。 Wednesday, September 11, 13
  15. 15. The project name will occur in several places in the built documentation. > Project name: sphinx_sinatra_example > Author name(s): sawanoboly 15 まだ対話が続くよ、 あと6ページほどやる。 Wednesday, September 11, 13
  16. 16. Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 1.0 > Project release [1.0]: 16 まだ対話が続くよ、 あと5ページほど。 Wednesday, September 11, 13
  17. 17. The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: 17 まだ対話が続くよ、あと4ページほど。 ああ、ここは好みで.txtに変えたりするね。 Wednesday, September 11, 13
  18. 18. One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: 18 まだ対話が続くよ、 あと3ページほど。 Wednesday, September 11, 13
  19. 19. Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/N) [n]: 19 まだ対話が続くよ、あと2ページほど。 オマケでepub出力ができるよ。kindleに入れようぜ。 Wednesday, September 11, 13
  20. 20. Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/N) [n]: y > doctest: automatically test code snippets in doctest blocks (y/N) [n]: > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: > coverage: checks for documentation coverage (y/N) [n]: > pngmath: include math, rendered as PNG images (y/N) [n]: > mathjax: include math, rendered in the browser by MathJax (y/N) [n]: > ifconfig: conditional inclusion of content based on config values (y/N) [n]: > viewcode: include links to the source code of documented Python objects (y/N) [n]: Y 20 まだ対話が続くよ、あと1ページほど。 いろんなモジュールあるけどスルーでOK、viewcodeはアリかな。 Wednesday, September 11, 13
  21. 21. A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [y]: y > Create Windows command file? (Y/n) [y]: n 21 Makefileを作って終わりです いざSphinx! Wednesday, September 11, 13
  22. 22. $ tree ├── Makefile # document build tasks ├── build # output directory └── source # reST files directory ├── _static ├── _templates ├── conf.py # Configration of sphinx for build └── index.rst # TopPage 22 初期のファイル構成こんな感じです。 すごい、もうビルドできるんだって! Wednesday, September 11, 13
  23. 23. $ make html sphinx-build -b html -d build/doctrees source build/html Making output directory... Running Sphinx v1.2b1 loading pickled environment... not yet created building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. 23 make html 早速ビルドだ、やったぜ! Wednesday, September 11, 13
  24. 24. $ tree build/html/ build/html/ ├── _sources │ └── index.txt ├── _static │ ├── ajax-loader.gif │ ├── basic.css │ ├── comment-bright.png │ ├── comment-close.png │ ├── comment.png │ ├── default.css │ ├── doctools.js │ ├── down-pressed.png │ ├── down.png │ ├── file.png │ ├── jquery.js │ ├── minus.png │ ├── plus.png │ ├── pygments.css │ ├── searchtools.js │ ├── sidebar.js │ ├── underscore.js │ ├── up-pressed.png │ ├── up.png │ └── websupport.js ├── genindex.html ├── index.html ├── objects.inv ├── search.html └── searchindex.js 2 directories, 26 files 24 build/htmlの下にファイルが現れた! よし、開いてみよう Wednesday, September 11, 13
  25. 25. 25 open build/html/index.html 私のドキュメントにようこそ すでにカッコイイじゃないですかー Wednesday, September 11, 13
  26. 26. write first page では書きたいことを 書きたいように書いていこう Wednesday, September 11, 13
  27. 27. add name to index.rst Contents: .. toctree:: :maxdepth: 2 27 Contents: .. toctree:: :maxdepth: 2 public APIリソースのpublicについて書いていくよ 準備はindex.rstに一行追加するだけでいいんだ。 Wednesday, September 11, 13
  28. 28. write source/public.rst 28 ※ convert from markdown by pandoc markdown版がもうあるので、pandocで変換してみたのがこちらです Wednesday, September 11, 13
  29. 29. Rebuild $ make html -- snip -- reading sources... [100%] public -- snip -- writing output... [100%] public -- snip -- Build finished. The HTML pages are in build/html. 29 さあ、もう一度ビルド! Wednesday, September 11, 13
  30. 30. open index.html 30 見出しが! 見出しが並んだよ! ああ、そうだねぼうや。 Wednesday, September 11, 13
  31. 31. mark up to index 索引があったらいいのに 本みたいに Wednesday, September 11, 13
  32. 32. add index before content POST /v1/public/***************** Resets the hogehoge 32 .. index:: single: public/reset POST /v1/public/****************** Resets the hogehoge そんなときは索引から飛びたい見出しの前に すこしおまじないをかけばうまくいくんだ。 Wednesday, September 11, 13
  33. 33. build and open genindex.html 33 自動でリンク付きの索引を? なんて素晴らしいんだ。 Wednesday, September 11, 13
  34. 34. Search! 検索機能もついてくるといっても、 必要な手続きやコツがあるんじゃないのかい? Wednesday, September 11, 13
  35. 35. Nothing to do いいえ、みなさんは何もする必要がありません。 Wednesday, September 11, 13
  36. 36. search for all documents 36 ドキュメントはビルドするだけで、searchの対象なんだ。 ※日本語対応してるかを見てない Wednesday, September 11, 13
  37. 37. Show raw reST file 少しの修正を施したいけど、 reSTの書き方をど忘れしたって? Wednesday, September 11, 13
  38. 38. 38 きっとshow source リンクをクリックするんだ。 Wednesday, September 11, 13
  39. 39. View reST on web browser 39 ほら、reSTファイルだ。 ※コンフィグで有効/無効 Wednesday, September 11, 13
  40. 40. Document Versioning アプリケーションのバージョンごとに 別のドキュメントにする必要が求められることがある。 Wednesday, September 11, 13
  41. 41. sphinx-build (Modify Makefile) Makefileで、ちょちょいのちょいなんだけど Wednesday, September 11, 13
  42. 42. Modify BUILDDIR BUILDDIR = build 42 BUILDDIR = build/1.0 他に良いやり方知ってる人教えてください Wednesday, September 11, 13
  43. 43. $ make html sphinx-build -b html -d build/1.0/doctrees source build/1.0/ html -- snip -- Build finished. The HTML pages are in build/1.0/html. 43 一応べつのディレクトリとして出力できるんだけど Wednesday, September 11, 13
  44. 44. upgrade mejour version このやり方があんまりスマートにも思えないんだ Wednesday, September 11, 13
  45. 45. conf.py and Makefile ## conf.py version = '1.1' release = '1.1' ## Makefile BUILDDIR = build/1.1 45 conf.pyはいいとしてもね Wednesday, September 11, 13
  46. 46. example of version selection! but modify template manually maybe... 46 Pythonの公式サイトみたいにしたいね Wednesday, September 11, 13
  47. 47. Appendix.1 Dash.app 知ってるかい Dash.app Wednesday, September 11, 13
  48. 48. Dash.app 48 ローカル本棚だよ Wednesday, September 11, 13
  49. 49. import from sphinx 49 doc2dashでググれ Wednesday, September 11, 13
  50. 50. Appendix.2 Publish to heroku htmlにしたら何処かでホスト必要がある、 herokuに置いてしまう方法を紹介しよう。 Wednesday, September 11, 13
  51. 51. static html publishing with sinatra http://qiita.com/sawanoboly@github/items/be1dbc9f19e93e4b62cf 51 今じゃないけど。 Wednesday, September 11, 13
  52. 52. Thanks ありがとう Wednesday, September 11, 13
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×