Building document with the Sphinx public edtion

Building documentwith the Sphinx

2013-09Public edtion

Wednesday, September 11, 13

この資料？• チームでアプリケーションつくってます

• APIリファレンスを管理しやすく・見やすくしよう

• チームメンバ向けにSphinxを紹介した時のスライドです

• 公開向けに加工しました

• 画像のぼかし

• 字幕

2Wednesday, September 11, 13

2008 Word3

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

2010 Dokuwiki4

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

2012 markdown based5

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

本当にそれでいいのでしょうか、いいえ

Lighitweight Documentation

http://www.slideshare.net/shimizukawa/blockdiag-jus20116

もっとコラボレーションしやすいものがあるのでは？

2013 Sphinx!!9

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

The Sphinx

• 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: Pandocuniversal docoment converter

ありがとうPandoc

Getting startedwith 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 [.]:

簡単スタートツール、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

赤い所が入力箇所！といっても、ほとんど入力する必要は無いんだけどね。

The project name will occur in several places in the built documentation.

> Project name: sphinx_sinatra_example

> Author name(s): sawanoboly

まだ対話が続くよ、あと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]:

まだ対話が続くよ、あと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]:

まだ対話が続くよ、あと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 filename.

> Name of your master document (without suffix) [index]:

まだ対話が続くよ、あと3ページほど。

Sphinx can also add configuration for epub output:

> Do you want to use the epub builder (y/N) [n]:

まだ対話が続くよ、あと2ページほど。オマケで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

まだ対話が続くよ、あと1ページほど。いろんなモジュールあるけどスルーで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

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

初期のファイル構成こんな感じです。すごい、もうビルドできるんだって！

$ make htmlsphinx-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 foundpickling 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... donebuild succeeded.

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

│ ├── 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

build/htmlの下にファイルが現れた！よし、開いてみよう

open build/html/index.html私のドキュメントにようこそ

すでにカッコイイじゃないですかー

write first page

では書きたいことを書きたいように書いていこう

add name to index.rstContents:

.. toctree::

:maxdepth: 2

Contents:

.. toctree::

:maxdepth: 2

public

APIリソースのpublicについて書いていくよ準備はindex.rstに一行追加するだけでいいんだ。

write source/public.rst

※ convert from markdown by pandocmarkdown版がもうあるので、pandocで変換してみたのがこちらです

Rebuild$ make html

-- snip --

reading sources... [100%] public

-- snip --

writing output... [100%] public

-- snip --

Build finished. The HTML pages are in build/html.

さあ、もう一度ビルド！

open index.html30

見出しが！見出しが並んだよ！ああ、そうだねぼうや。

mark upto index

索引があったらいいのに本みたいに

add index before contentPOST /v1/public/*****************

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resets the hogehoge

.. index::

single: public/reset

POST /v1/public/******************

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resets the hogehoge

そんなときは索引から飛びたい見出しの前にすこしおまじないをかけばうまくいくんだ。

build and opengenindex.html

自動でリンク付きの索引を？なんて素晴らしいんだ。

Search!

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

Nothing to do

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

search for all documents36

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

Show raw reST file

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

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

View reST on web browser

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

DocumentVersioning

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

sphinx-build(Modify Makefile)

Makefileで、ちょちょいのちょいなんだけど

Modify BUILDDIRBUILDDIR = build

BUILDDIR = build/1.0

他に良いやり方知ってる人教えてください

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

一応べつのディレクトリとして出力できるんだけど

upgrademejour version

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

conf.py and Makefile## conf.py

version = '1.1'

release = '1.1'

## Makefile

BUILDDIR = build/1.1

conf.pyはいいとしてもね

example of version selection!but modify template manually maybe...

Pythonの公式サイトみたいにしたいね

Appendix.1Dash.app

知ってるかい Dash.app

Dash.app48

ローカル本棚だよ

import from sphinx49

doc2dashでググれ

Appendix.2Publish to heroku

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

static html publishing with sinatrahttp://qiita.com/sawanoboly@github/items/be1dbc9f19e93e4b62cf

今じゃないけど。

Thanks

ありがとう

Building document with the Sphinx public edtion

Technology

Transcript of Building document with the Sphinx public edtion

النظام الوطني للاعتماد › Documents › Accreditation-Scope-NAL038.pdfBS 8539 BS 1881 Part 207 APHA 4500 H.2017 23rd edtion APHA 2540 02017 23rd edtion APHA 2540

Sphinx referenzen verkauslokale 2015

Xapian vs sphinx

CMU Sphinx

Sphinx referenzen gastronomie 2014

Sphinx programma herfst 2014

Sphinx referenzen 2014

Нагруженный поиск на Sphinx

Yi mu exhibition services co.,ltd. new edtion 2012

Sphinx Basilique - Sphinx Tegels · Sphinx Basilique Collection. Collection BASILIQUE grey . De krachtige, statige uitstraling van de Maastrichtse Onze Lieve Vrouwe Basiliek vormde

sphinx (1)

Le Sphinx Des Glaces

Cours Sphinx Lexica

INTRODUCTION AU LOGICIEL SPHINX

YiMu exhibition services co.,ltd. new edtion 2012 for 2013

Initialisation Sphinx

INTRODUCTION AU LOGICIEL SPHINX Sphinx est un logiciel d ...

Langgaard - Sphinx Tableau Musical

5 2 SPHINX 105 kann an Decke und Wand montiert werden, mit ...€¦ · SPHINX 105-110 SPHINX 105-220 SPHINX 105-300 Seitenansicht Seitenansich tSe an si ch Draufscht Draufsi cht Draufsicht-10

12th Edtion Part 2