Building document with the Sphinx public edtion

Building document
with the Sphinx
2013-09
Public edtion
Wednesday, September 11, 13

この資料？
• チームでアプリケーションつくってます
• APIリファレンスを管理しやすく・見やすく
しよう
• チームメンバ向けにSphinxを紹介した時の
スライドです
• 公開向けに加工しました
• 画像のぼかし
• 字幕
2

2008 Word
3
2008年、プロジェクトのドキュメントはWordで作られていました
この方式の欠点はみなさんご存知のとおりでしょう

2010 Dokuwiki
4
2010年のプロジェクトではphpのアプリケーションを使いました。
版の管理、手軽さは飛躍的に向上しました、環境の管理が必要でした。

2012 markdown based
5
2012年にはmarkdownを変換する自作のRubyアプリケーションで
APIリファレンスを提供しました。

2013 Github pages ?
6
そして2013年、GithubのWikiにリファレンスを書き始めましたが...

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
もっとコラボレーションしやすいものがあるのでは？

2013 Sphinx!!
9
そうだ、Sphinxでいこうよ。
これはGithub wikiのMarkdownを単純に変換したものです。

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の世界

Tool: Pandoc
universal docoment converter
11
ありがとうPandoc

Getting started
with the Sphinx !!
今夜できる、Sphinx ドキュメンテーション

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との対話を
フルコーラスでご覧ください

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
赤い所が入力箇所！
といっても、ほとんど入力する必要は無いんだけどね。

The project name will occur in several places in the built
documentation.
> Project name: sphinx_sinatra_example
> Author name(s): sawanoboly
15
まだ対話が続くよ、
あと6ページほどやる。

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ページほど。

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に変えたりするね。

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
ﬁlename.
> Name of your master document (without suﬃx) [index]:
18
あと3ページほど。

Sphinx can also add conﬁguration for epub output:
> Do you want to use the epub builder (y/N) [n]:
19
オマケでepub出力ができるよ。kindleに入れようぜ。

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
いろんなモジュールあるけどスルーでOK、viewcodeはアリかな。

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！

$ 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
初期のファイル構成こんな感じです。
すごい、もうビルドできるんだって！

$ 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
早速ビルドだ、やったぜ！

$ 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
│ ├── ﬁle.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 ﬁles
24
build/htmlの下にファイルが現れた！
よし、開いてみよう

25
open build/html/index.html
私のドキュメントにようこそ
すでにカッコイイじゃないですかー

write ﬁrst page
では書きたいことを
書きたいように書いていこう

add name to index.rst
Contents:
.. toctree::
:maxdepth: 2
27
Contents:
.. toctree::
:maxdepth: 2
public
APIリソースのpublicについて書いていくよ
準備はindex.rstに一行追加するだけでいいんだ。

write source/public.rst
28
※ convert from markdown by pandoc
markdown版がもうあるので、pandocで変換してみたのがこちらです

Rebuild
$ make html
-- snip --
reading sources... [100%] public
-- snip --
writing output... [100%] public
-- snip --
Build ﬁnished. The HTML pages are in build/html.
29
さあ、もう一度ビルド！

open index.html
30
見出しが！見出しが並んだよ！
ああ、そうだねぼうや。

mark up
to index
索引があったらいいのに
本みたいに

add index before content
POST /v1/public/*****************
Resets the hogehoge
32
.. index::
single: public/reset
POST /v1/public/******************
Resets the hogehoge
そんなときは索引から飛びたい見出しの前に
すこしおまじないをかけばうまくいくんだ。

build and open
genindex.html
33
自動でリンク付きの索引を？
なんて素晴らしいんだ。

Search!
検索機能もついてくるといっても、
必要な手続きやコツがあるんじゃないのかい？

Nothing to do
いいえ、みなさんは何もする必要がありません。

search for all documents
36
ドキュメントはビルドするだけで、searchの対象なんだ。
※日本語対応してるかを見てない

Show raw reST ﬁle
少しの修正を施したいけど、
reSTの書き方をど忘れしたって？

38
きっとshow source リンクをクリックするんだ。

View reST on web browser
39
ほら、reSTファイルだ。
※コンフィグで有効/無効

Document
Versioning
アプリケーションのバージョンごとに
別のドキュメントにする必要が求められることがある。

sphinx-build
(Modify Makeﬁle)
Makeﬁleで、ちょちょいのちょいなんだけど

Modify BUILDDIR
BUILDDIR = build
42
BUILDDIR = build/1.0
他に良いやり方知ってる人教えてください

$ make html
sphinx-build -b html -d build/1.0/doctrees source build/1.0/
html
-- snip --
Build ﬁnished. The HTML pages are in build/1.0/html.
43
一応べつのディレクトリとして出力できるんだけど

upgrade
mejour version
このやり方があんまりスマートにも思えないんだ

conf.py and Makeﬁle
## conf.py
version = '1.1'
release = '1.1'
## Makeﬁle
BUILDDIR = build/1.1
45
conf.pyはいいとしてもね

example of version selection!
but modify template manually maybe...
46
Pythonの公式サイトみたいにしたいね

Appendix.1
Dash.app
知ってるかい Dash.app

Dash.app
48
ローカル本棚だよ

import from sphinx
49
doc2dashでググれ

Appendix.2
Publish to heroku
htmlにしたら何処かでホスト必要がある、
herokuに置いてしまう方法を紹介しよう。

static html publishing with sinatra
http://qiita.com/sawanoboly@github/items/be1dbc9f19e93e4b62cf
51
今じゃないけど。

Thanks
ありがとう

Building document with the Sphinx public edtion

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (20)

Similar to Building document with the Sphinx public edtion

Similar to Building document with the Sphinx public edtion (20)

More from Yukihiko SAWANOBORI

More from Yukihiko SAWANOBORI (10)

Building document with the Sphinx public edtion