Sphinx Advent Calendar 2012

sphinxに関わる内容ならどんな内容でも構いません。ゆるい感じでいきましょう。ネタがかぶってもOK、使い回しもOK、気にしない！ :

- 1日目: Sphinx mobi builder

- 2日目: Sphinxで文章を書く際のEmacs環境設定 2012.12版

- 3日目: 今年のSphinx 生活を振り返って

- 4日目: Sphinx + blockdiag による非プログラマのための使える図解の紹介

- 5日目: テーマに少し手を入れてちょっとだけ使いやすくる

- 6日目: Sphinx と MeCAB でナレッジベース風ツールを作る

- 7日目: 異なった環境で Sphinx と blockdiag とかを使う

- 8日目: intersphinxを使おう - #sphinxjp アドベントカレンダー2012

- 9日目: Sphinxから見えるドキュメント作成の過去、現在、未来

- 10日目: 本家 Sphinx Advent Calendar 2012 10日目 ～サクラエディタから make html～

- 11日目: Sphinxで手順書を作ってみませんか？

- 12日目: Sphinx-Users.jpを作った時のお話

- 13日目:「最近更新したページ一覧」を生成するsphinx拡張、recentpages

- 14日目: Sphinxで出力フォーマットごとに記述を変更する

- 15日目: pandoc で Redmine の Wiki を Sphinx に変換しよう

- 16日目: Sphinx Advent Calendar 16日目

- 17日目: Tinkererでブログを書こう

- 18日目: "ドキュメントを部分的に公開/非公開にしてビルドする"の実用例

- 19日目: Sphinx 文書に markdown フォーマットを利用する

- 20日目: Sphinxで図に番号をつける

- 21日目: SphinxでCSSのclassを変更する

- 22日目: Sphinx アドベントカレンダー22日目

- 23日目: Sphinxで薄い本を書いてみた

- 24日目: Start Sphinx Documentation

- 25日目: Sphinxの過去と、未来

1日目: Sphinx mobi builder

- 著者: @r_rudi

- 原文

Sphinx Advent Calendar 2012 の一日目です。

昨年は技評さんがいろいろなアドベントカレンダーをePub化してくれました 参考 。

SphinxはePub builderが標準で付いてきますので、ePubに簡単に出来ます。

ただし、sphinx-quickstartを実行した時に、ePubを作るかと聞かれるのに、y を答えてください。

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

そうしておけば、 make epub と打つだけでepubにしてくれます。

mobi

話は変わりますが、ついに Kindle が日本でも発売されましたね。しかし、 KindleはそのままではePubは読み込めません。

というわけで、 mobi builderというのがあります。

実装は今のところたぶん二つあります。

1. mobi-builder

2. kindlebuilder

1つめは最近更新されました。でも、読むと分かるのですがこれはePubにちょっと手なおしたものを吐き出して、kindlegenで変換するという形式のようです。

2つめは某前会長作です。こっちはmobi形式のheaderや圧縮方式であるpalmdoc までpythonで実装されているという本格派です。さすがです。

ということで、後者のほうを使ってみましょう。

kindlebuilder

まずはレポジトリからcloneします。

% cd ~/Works/
% hg clone https://bitbucket.org/shibu/kindlebuilder

あとは、conf.pyを以下のように書き換えるだけです。

sys.path.insert(0, os.path.abspath('/home/r_rudi/Works/kindlebuilder/'))
extensions = ['kindlebuilder']

あとはこう打ちます。

% sphinx-build -b kindle -d _build/doctrees   . _build/kindle

ずらずらと出てきたあとで、 _build/kindle/以下に default.azw というファイルができますので、あとはこれをkindleに送ればOKです。

OKです…

あ、あれ…

kindleに送ってもリストに出てきませんね…

しょうがない

kindlegenを使うことにします。

1. ここ からkindlegenをダウンロード

2. make epub

3. kindlegen hoge.epub

これで、 hoge.mobi ファイルが生成されます。さすが謹製だけあってほぼ完璧です。

最初っからこっち使えばいいじゃん、と言うのは却下です。

一応

がんばってkindle previewerで表示できるようにはしました。正確には、 mobi header内ではtitleが32byteとなってるんですが、長い場合はそのまま 32byte以上になってた、という問題で32byteで切るようにしただけです。

https://bitbucket.org/r_rudi/kindlebuilder

でも、Kindle paperwhiteに送ってもだめなんですよねぇ…

しょっぱなから中途半端で大変申し訳ないのですが、ゆるふわということで許してください。

次は @ymotongpoo 先生です。先生、お願いします！

2日目: Sphinxで文章を書く際のEmacs環境設定 2012.12版

- 著者: @ymotongpoo

- 原文

はじめに

こんにちは、Python界の情弱です。このエントリはSphinx Advent Calendar 2012の2日目のエントリです。1日目の@r_rudiより受け取りました。完全に使い回しのネタ＋αとなってますがご容赦下さい。

- Sphinx Advent Calendar 2012 - connpass

最近はVimだとかSublime Text 2だとか、若者のEmacs離れが進んでおりますが、みなさんはいかがお過ごしでしょうか。SphinxはreStructured Textでドキュメントを記述しますが、Emacsを使うと結構色々と便利だよ、という事をお知らせしたく、この文章を書いています。

rst.el

rst.elの導入

Docutilsが配ってます。Emacs用の拡張しか置いてないです。

- http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils/tools/editors/emacs/rst.el

どうだ、Vimmer、参ったか！Sublime Text 2の人も参れ！（白目）

以前似たような記事を書いたのですが、多方面より「キーアサインが変わってる！」との報告を受けましたので再度まとめます。

;;;; rst.el
;; Emacs起動時にrst.elを読み込み
(require 'rst)
;; 拡張子の*.rst, *.restのファイルをrst-modeで開く
(setq auto-mode-alist
(append '(("\\.rst$" . rst-mode)
("\\.rest$" . rst-mode)) auto-mode-alist))
;; 背景が黒い場合はこうしないと見出しが見づらい
(setq frame-background-mode 'dark)
;; 全部スペースでインデントしましょう
(add-hook 'rst-mode-hook '(lambda() (setq indent-tabs-mode nil)))

ショートカット

見出しを表示のオプションは大きなreSTファイルを書いているときはとても便利です。

autoinsertでテンプレートを利用

今日日のEmacsでは新規ファイルを作成する際にテンプレートを挿入できる autoinsertが標準で利用できます。これで毎度書く文字コードの設定を回避できて大変良いです。

;;;; autoinsert
(require 'autoinsert)

(setq user-id-string "ymotongpoo")
(setq user-full-name "Yoshifumi YAMAGUCHI")
(setq user-mail-address "ymotongpoo AT gmail.com")

;; テンプレートのディレクトリ
(setq auto-insert-directory "~/.emacs.d/template")

;; 各ファイルによってテンプレートを切り替える
(setq auto-insert-alist
(nconc '(
("\\.rst$" . ["template.rst" my-template])
) auto-insert-alist))
(require 'cl)

(defvar template-replacements-alists
'(("%file%"             . (lambda () (file-name-nondirectory
(buffer-file-name))))
("%file-without-ext%" . (lambda () (file-name-sans-extension
(file-name-nondirectory (buffer-file-name)))))
("%date%" . (lambda() (current-time-string)))
("%mail%" . (lambda () (identity user-mail-address)))
("%name%" . (lambda () (identity user-full-name)))
("%id%" . (lambda () (identity user-id-string)))
))

(defun my-template ()
(time-stamp)
(mapc #'(lambda(c)
(progn
(goto-char (point-min))
(replace-string (car c) (funcall (cdr c)) nil)))
template-replacements-alists)
(goto-char (point-max))
(message "done."))
(add-hook 'find-file-not-found-hooks 'auto-insert)

で、.emacs.d/templateにテンプレートを置いておく。

- .emacs.d/template/template.rst

.. -*- coding: utf-8 -*-
Date: %date%
Author: %id% (%name%, %mail%)

.. _%file-without-ext%:

これで毎度書くコードが減って大変いいですね。

watchdogによる自動ビルド

watchコマンドでビルドしてもいいんですが、Pythonユーザなのでwatchdogでビルドします。

- omakeもmakeも使わずに、Sphinxドキュメントの継続的ビルド - Study08.net 対シンバシ殲滅用人型機動兵器

watchmedo shell-command --patterns="*.rst" --recursive --command='make html' source

おわりに

ところでこれからHTML5が標準になるので、そろそろSphinxもXHTML 1.0ではなくデフォルトはHTML5で記述してもらえるようにしてほしいなと思ったりしている今日この頃です。

明日は世界（@tk0miya）です。世界、お願いします。

3日目: 今年のSphinx 生活を振り返って

- 著者: @tk0miya

- 原文

このエントリは Sphinx Advent Calendar 2012 の3日目のエントリです。2日目の@ymotongpooより受け取りました。僕はプレーンな vim 使い(意訳: 特に設定してない)なのですが、Emacs の人は この記事 を見ておくといいと思います。

今年を振り返る

Advent Calendar ということで何を書こうかいろいろ考えてみたのですが、なんとなく今年の Sphinx 生活を振り返ろうというゆるゆるのエントリーにすることにしました。濃い技術話を期待されていた方、すみません。

SphinxCon JP 2012

Sphinx (-users.jp) の今年について振り返るにあたって、重要なのは SphinxCon JP 2012 ですね。 (観測範囲内では) 世界で初めての Sphinx のカンファレンスで、7つのセッションとスプリントが開催されました。詳しくはレポートページに譲りますが、立ち見が出るほどの盛況っぷりでまだまだ多くの人の関心を集めることができるようです。

僕はこのイベントでは 全体の紹介となる発表 をしましたが、 Sphinx はまだいろんな可能性を秘めているし、やらねばならないことはたくさんありそうです。

SphinxCon JP 2012 の系譜としては、来年 2月に OSC 併催イベントとして SphinxCon JP 2013 Spring が開かれます。副会長の @shimizukawa と話していたのですが、これまで Sphinx を通していろんな人たちと出会ってきたこともあり、また楽しい出会いがあるといいなあ、と楽しみにしています。手伝ってくれる方も募集していますので、興味がある人は声をかけてくださいね！

Sphinx ハンズオン

去年の 12月にはじめて、その後 5,6 回開かれている Sphinx ハンズオンですが、実は最初は アート・オブ・コミュニティ を読んでいて思いつきではじめたものです。初心者の人に向けたイベントをやることで、いろんな人に広まるといいなという「バズの波」を起こそうという狙いのもとにスタートしました。成果は上々で、(ちゃんと数えていませんが)6〜80人近い方々が Sphinx に触るきっかけになったんじゃないかと思います。

また、僕自身は「最初の 3回でやめる。あとは他の人に任せたい」と公言してきましたが、西では Sphinx 朝会が(ほぼ同時期に)始まったり、他の講師陣によるサポートがあってぼちぼち継続しています。「Sphinx を広める」というのが目的なので、徐々に広がりが見えるというのはとても嬉しいですね。

僕が開く Sphinx ハンズオンは一旦終了したのですが、また期を見て開催してもいいかな、と思ってます。やってほしい！という人は声をかけておいてください。声が大きければ近いうちに一緒にやりましょう :-) もちろん、「オレが開催してやるぜ！」という方も大歓迎です。

Sphinx+翻訳 Hack-a-thon

Sphinx ハンズオンが初心者向けなのに対して、玄人向け? なのが Sphinx+翻訳 Hack-a-thon です。その前の年(2011)はあまり定期的に開催できていなかったので、年初に今年はちゃんと毎月開催しようと狙っていました。 イベントページ を見てみると、他の Sphinx イベントを開催した1,9月を除いて、ほぼ毎月開催できているようです。

Hack-a-thon はもくもく形式なので、ひたすら作業をしたり、だらだらおしゃべりしたりとゆる〜い感じで開催しています。来年も同じペースで開いていこうと思っているので気が向いた時に参加してみてください。

Sphinx 系の開発

ひたすら blockdiag を改造し続けていた覚えしかなかったのですが、

- slide: スライドを埋め込む拡張

- webmocks: 画面仕様っぽいものを作る拡張

- googlemaps: Google マップを埋め込む拡張

などの拡張をリリースしたり、gist に小物を作って遊んでいました。

- remoteinclude: URL を指定可能な literalinclude っぽいもの

- fancybulletlist: ラフに箇条書きを書いても、綺麗に整形してくれる拡張

- section_autoref: セクションを作ると自動的にラベルを作ってくれる拡張

- wikitable: WiKi のテーブル記法もどきに対応する

すごく役に立つ機能をリリースはできなかったのですが、ちょっとしたところで役に立つのではないかと思います。気になったら使ってみてください。

また、ちょっとずつ Sphinx の中がわかってきたので、いつかまとめエントリーが書けるといいなあと思っています。

まとめ

振り返ってみると、実は Sphinx 漬けな一年でした。

Sphinx 自体もあんなところやこんなところ、はたまたそんなところで使われたりとあちこちで使ってるという話を耳にしています。使ってもらっている話を聞くと、イベントなどをやっていて報われた気分になりますね。

少し気は早いですが、来年も Sphinx にとっていい年になりますように祈ってこのエントリーを終わりにします。

それでは、明日の @sojimn さんのエントリーをお楽しみに！

4日目: Sphinx + blockdiag による非プログラマのための使える図解の紹介

- 著者: @sojimn

- 原文

はじめに

こんにちは。 Sphinx Advent Calendar 2012 の4日目のエントリです。 @tk0miyaより受け取りました。

Sphinxを使い始めてまだ日が浅いですが実際に仕事で使ってみてすばらしいツールだと今更ながら気づき、Sphinxに特化したエントリというよりも Sphinx + blogckdiagを使って仕事に使えるダイアグラムの表現方法についてご紹介します。

非プログラマでも簡単に作成ができ修正も簡単、イライラしないでサクサクと図が書けます。

ソフトウェア開発プロジェクトで作成されるドキュメント(特にマニュアルで利用)は顧客に説明するための図解を多用します。これまでの経験で

- Word/Excel の描画ツールをつかってがんばって作った図調整と編集がとても大変

- Visio を使ってわかりやすく綺麗に作成されているが、Word/Excel/PowerPointに貼り付け、画像のため編集が手間

- 最近増えたと思われる開発環境としての Mac利用者で使える描画ツールがほしい

- Mac では OmniGraffleというすばらしいツールがありますが全員分のライセンスは難しい

このような状態でした。Visio や Omnigraffleは愛用しておりすばらしいツールですがもっとお手軽な描画ツールが欲しいとさがした結果、Sphinx + blockdiag という組み合わせが実用的なことに今更ながら気づきました。基本的な Sphinx / blogckdiagの使い方ではなく、仕事で使える図解例のコードを紹介したいと思います。

図解のためのフォーマット

Sphinx + blockdiagでどのようなことができるでしょうか。仕事で使えると思うパターンを以下の図をコードとともに紹介します。

1. 手順…順番に説明するとき、ステップや時系列説明

2. リスト…グループ毎に分かれた場合の説明

3. リング/循環…連続したプロセスの説明

4. 階層…重み付けされたモノの説明

5. 集合の関連…グループの関連、アイデア、マインドマップ

6. マトリクス…関連度合いの説明など

1. 手順

ステップや時系列説明に利用するダイアグラムです。

.. blockdiag::

blockdiag {
A [label = "ネタを探す"];
B [label = "記事を書く"];
C [label = "推敲する"];

A -> B -> C;

}

2. リスト

ダイアグラムと対応した説明をつけています。 :desctable: を利用すると説明表を自動生成してくれます。

.. blockdiag::
:desctable:

blockdiag {
A [numbered = 1, label = "オペレーティングシステム", description
= "CentOS 6.3"];
B [numbered = 2, label = "ミドルウェア", description = "Apache
2.4 / Python 2.7.2 / Django 1.4.2"];
C [numbered = 3, label = "データベース", description =
"PostgreSQL 9.2.1"];

A -- B -- C;

// 配置
node_width = 220;
span_width = 20;
span_height = 20;
}

3. リング/循環

連続したプロセスなどの説明に利用するダイアグラムです。

.. blockdiag::

blockdiag {
default_shape = roundedbox
node_width = 160;

A [label = "タスク準備"];
B [label = "プランニングミーティング"];
C [label = "タスク割当"];
D [label = "デモンストレーション"];
E [label = "中間ミーティング"];
F [label = "デイリースクラム"];

A -> B -> C;
D <- E <- F;
C -> F [folded];
D -> A [folded];
}

4. 階層

プロジェクトチーム、組織など重み付けがある情報の説明に利用するダイアグラムです。

.. blockdiag::

blockdiag {
//縦書きモード
orientation = portrait

A [label = "プロジェクトチーム"];
B [label = "開発チーム"];
C [label = "斉藤"];
D [label = "高山"];
G [label = "品質チーム"];
H [label = "佐藤"];
I [label = "田辺"];

A -> B -> C;
B -> D;
A -> G;
G -> H;
G -> I;
}

5. 集合の関連

グループの関連、グループのメンバーなど集合に関するダイアグラムです。

.. blockdiag::

blockdiag {
A [label = "スクラムチーム"];
B [label = "クロダ"];
C [label = "サカモト"];
D [label = "タニグチ"];
E [label = "コンドウ"];
F [label = "サトウ"];
G [label = "ナカジマ"];
H [label = "ソウマ"];
I [label = "キタダ"];
J [label = "コジマ"];

A -- B -- C -- D;
A -- E -- F -- G;
A -- H -- I -- J;

group first_group {
label = "設計チーム"
B; C; D;
}

group second_group {
label = "開発チーム";
color = "#77FF77";
E; F; G;

}

group {
label = "試験チーム";
color = "#FF0000";
H; I; J;
}
}

6.マトリクス

ここまで来ると無理矢理感がすごいですが、マトリクスっぽいダイアグラムです。

.. blockdiag::

blockdiag {
A -- B [style = none];
C -- D [style = none];
B -- D [style = none, folded];
C -- A [style = none, folded];

// ブロックのサイズと余白指定
node_width = 200;
node_height = 100;
span_width = 5;
span_height = 5;

}

さいごに

いくつか blockdiag でやる必要の無い図がありますが、例ということでご了承ください。

Sphinx + blockdiag でこのような表現が簡単にできます。 ブロック図生成ツー ル blockdiag の属性の説明にはさらに細かい設定が可能で作成したいダイアグラムに合わせた調整ができます。

実際に仕事で使ったときに自分達ルールというか、非プログラマでもドキュメント作成できるような環境のお膳立てをしました。優れている点は

- テキストエディタで作成可能

Windows/Mac/Linux 関係なく利用可能

- 非プログラマでも簡単に習得可能

ドキュメントに合わせたtoctreeとファイル群を事前に用意。担当にテキスト作成を依頼するだけ。

- シンプルでさくさく書けること

仕事で利用する場合雛形を事前に作成、最低限の書式のみというルール。ドキュメント作成者の技術スキルに関係なく文書作成だけに集中してもりもり作成してもらえる。

- 図の修正が簡単(苦痛がない、これは結構重要)

Excelの描画ツールではなく、図の描画は専用ツール使おうよ。と思っている。

- 見た目重視の図、複雑な図ははじめから専用ツール(visio,Omnigraffle)を利用

自分の要求を満たした Sphinx + blockdiag という組み合わせはおすすめです。

次回のエントリは @togakushi です。お楽しみに。

5日目: テーマに少し手を入れてちょっとだけ使いやすくる

- 著者: @togakushi

- 原文

この記事は Sphinx Advent Calendar 2012 の5日目の記事です。@sojimn さんから受け取りました。

Sphinx を利用してるサイトでサイドバーやナビゲーションバーにリンクがあるのをよく見かけます。 Sphinx-users.jp で公開されているドキュメントもその例のひとつです。

この記事ではサイドバーやナビゲーションバーに好みのテキストやリンクを追加するテンプレートの使い方を紹介します。

テンプレートに関するドキュメントについては以下も参考にしてください。

- テンプレート http://sphinx-users.jp/doc11/templating.html

- テンプレートを継承する http://sphinx-users.jp/cookbook/makingwebsite/template.html#extends

- Google AnalyticsやGoogle Adsenceを貼りたい http://sphinx-users.jp/reverse-dict/html/google.html

テンプレートには Jinja が利用されています。この記事では必要なものだけをピックアップしていきます。

テンプレートで使う文法

Jinja では波カッコで囲まれている部分は特別な意味を持ち、それ以外の部分は通常の html として扱われます。難しいことは抜きにして、以下の使い方を覚えるだけで十分です。

よく使うタグの意味

{{ ... }}

変数や関数を展開します。

{% ... %} / {%- ... -%}

forループなどの式を実行する際に使用します。

テンプレートの継承などにも使用します。

% の前後に - がある場合はテンプレート展開後のスペースを削除します。

{# ... #}

コメントです。

実際に使うものは以下の３つだけです。

{% extends %}

ベースとなるテンプレートを指定します。

Sphinx の場合、テーマに含まれている layout.html を指定します。

{% block %} / {% endblock %}

テンプレートを継承して上書きしていきます。

{{ super() }}

block で継承したテンプレートの元の内容を埋め込みます。

基本的な使い方:

{% extends "!layout.html" %}
{% block テンプレート名 %}
{{ super() }}
{% endblock %}

とてもかんたんですね！

テンプレートを継承して書き換える

Sphinx で使用されている多くのテーマは basic テーマをベースにしています。 basic テーマで使用されているテンプレート名は公式ドキュメントで確認することができます。ここではサイドバーとナビゲーションバーに絞って記述します。

まずはテンプレートを継承できるように、 _templates ディレクトリの中に layout.html という名前でファイルを作ります。

内容はこの１行だけです。

{% extends "!layout.html" %}

これで使用しているテーマの layout.html をベースにカスタマイズする準備ができました。

この状態のまま make html を実行してもエラーもなんの変化もありません。 layout.html に何も書かないとテンプレートのレイアウト情報もなにもないので白紙のページが出来上がります。忘れずに記述しましょう。

実際にテンプレートを継承してカスタマイズするには以下の様にしていきます。

サイドバーの目次の前後に新しい項目を追加する

sidebartoc はサイドバー内にある目次のテンプレートです。

他のドキュメントへのリンクやリポジトリへのリンクを作っておくと便利に使えます

適応例:

{% extends "!layout.html" %}
{% block sidebartoc %}
<h3>ドキュメント</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="http:// ... /">Doc1</a></li>
<li class="toctree-l1"><a class="reference internal" href="http:// ... /">Doc2</a></li>
<li class="toctree-l1"><a class="reference internal" href="http:// ... /">Doc3</a></li>
</ul>
{{ super() }}
<h3>リポジトリ</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="://bitbucket.org/">bitbucket</a></li>
</ul>
{% endblock %}

組み込みテーマの nature に適応するとこのような感じになります。

リレーションバーの前後に新しい項目を追加する

リレーションバーはページの先頭とフッターの手前の２つが存在します。 relbar1 は上、 relbar2 は下のリレーションバーのテンプレートです。

このテンプレートはリレーションバーの内容を書き換えるものではないので注意してください。

ページ先頭のリレーションバーの前後にテキストを追加する例:

{% extends "!layout.html" %}
{% block relbar1 %}
【ここは前】
{{ super() }}
【ここは後】
{% endblock %}

組み込みテーマの nature に適応するとこのような感じになります。

フッター前のリレーションバーを消す例:

{% extends "!layout.html" %}
{% block relbar2 %}
{% endblock %}

リレーションバーのメニューに項目を追加する

rootrellink はリレーションバーの中に表示されているパンくずリストのテンプレートです。

適応例:

{% extends "!layout.html" %}
{% block rootrellink %}
<a href='http://google.com/'>google</a> {{ reldelim2 }}
{{ super() }}
{% endblock %}

組み込みテーマの nature に適応するとこのような感じになります。

ここで使用している reldelim2 はリレーションバーの区切り記号です。「前へ」「次へ」「索引」などで使われている区切り記号(デフォルト ' |' )を指定しています。

その他

- 実際にどのようなレイアウトで表示するかはベースのテーマで定義されていますので、block で指定するテンプレート名はどの順序で記述しても問題ありません。

- 存在しないテンプレート名を指定してもエラーにはならず、表示もされません。

- 他にもいろいろなテンプレートがあるので、いろいろ試してみるとよいでしょう。

ちなみに

公式ドキュメントには「バージョン 1.0 で撤廃.」となっているものも使えるのはなんでだろ。。。ｗ

次は @GoingMyWayNet さんです。よろしく！

6日目: Sphinx と MeCAB でナレッジベース風ツールを作る

- 著者: @goingmywaynet

- 原文

これは Sphinx Advent Calendar 2012 6日目です。@togakushi さんから受け取りました。 @togakushi さんのテーマに関するテーマ（私の表現がアレですね..）を今後参考にしながら社内のsphinxサイトをリニューアルしたいなと思う今日この頃です。

さて、 @goingmywaynet です。Python使えない自称エンジニア（本業は事務屋）ですが、面白くてSphinxを利用させて頂いています。ネタの使い回しになりますが、ちょっと変わったSphinx の使い方のご紹介です。 Tipsや技術的な内容は薄いと思いますが、お付き合い頂ければと思います。

１．Sphinx とは

Advent Calendarからこられた方には説明の必要はないと思いますが、Sphinxは元々は Pythonというプログラミング言語のメンテナンスやAPIのためのドキュメントを作成するツール(ドキュメントツール）でした。私が興味深いと思う以下の様な特徴があります。

- クロスリファレンス機能

- toctreeによるドキュメントの階層化

- 複数の出力フォーマット を一つのソースで（HTML , PDF , ePUB , etc..)

- 日本ユーザーグループ がある

コードハイライト機能やBlockdiagなどの多彩な機能やアドインがあることから、主にエンジニアの間でドキュメントを書く為のツールとして活用されてますが、これを非エンジニアの領域で使ってみました。

２．Sphinxの活用環境と動機

windows 端末と windows共有フォルダが組まれたごくごく一般的な事務屋さんの環境において、私たちは以下の様な課題を抱えていました。

- 共有フォルダがカオス（「新しいフォルダ〜コピー」「新○○」「New○○」..）

- 情報が分散（紙、doc、xls、PDF、誰かの頭の中.. )

- 情報の出自がバラバラ（課内文書、社内文書、社外文書、色々なクリップ）

- 書式が統一されていない（まあ、いろいろ書き方有るよね..）

- 経緯がわからない。結論が分からない。更新されない。

ちなみに、"マニュアル"という名の「何となく判るけど、実施するには情報が足りないモノ」をかなり目にしてきました。（特にQMSとかISOとかで作らされる資料に多い気がする）さらに、人的環境として以下の様な課題を抱えていました

- 人は異動するもの

- 技術継承は OJT! OJT! OJT!

- ノウハウを最も持っている者から離れていく

- ある日、中心人物が食中毒になったら業務が止まる

そこで、 各人が自分の資料やPCや脳裏や共有フォルダの奥深くに溜め込んだ情報やノウハウを手軽に洗い出し、その情報を集約／整理する環境 を必要としていました。(ちなみに、運用ドキュメントにおけるsphinxの可能性については @tcsh さんの Operation Document Model がとてもとても参考になります ) ただし、

- 文書管理システムとか導入するのも管理するのもめんどい

- 滅多にない作業やすでに終わった仕事の手順書とか書くの面倒いし頼み難い

- 決済書類とか書くのめんどい

- すでにある情報を決まった形式に書き換えるのめんどい

- 情シス部門じゃないので Admin 権限もってない

ということで、制約の中で出来る限りの事をしようということで、Sphinxを活用して情報の整理に取り組んでいます。（これを仮にKnowledge Base と呼びます） 利用者も、"make html" とかコマンドを叩く事にすら抵抗がある（の割りには Microsoft Word / Excel / PowerPointなら使いこなす）メンバーが多いので、とにかく簡単に情報を集約できる仕組みを目指しました。

３．Sphinx による仕組み

Sphinxを活用して、共有フォルダに分散している、各種情報に対するインデックを持つWebページを作ってしまう事にしました。機能的にはざっくり以下の様な通りです

1. 特定Window共有フォルダ配下を再帰検索

2. 指定のファイル名（アンカーファイル）を見つけたらそのファイルを.rstとして扱う（もちろん、アンカーファイルは reST 形式で記述）

3. SphinxでHTMLを生成する際にアンカーファイルの有ったディレクトリへのリンクを自動挿入（実際は.rstファイル生成時に記述している）

4. 上記の繰り返しで、共有フォルダ内の必要な情報（のインデックス）をHTMLに集約していく

5. sphinx のお陰でHTML内での検索も可能

生成されるHTML / ここから各種情報へ辿れる

各情報へのリンクは自動で生成

ここでいう「アンカーファイル」とは特定のファイル名を持つSJISのCR/LF改行コードファイルです。課員には自分の持つ情報について、

- 共有フォルダに既にあるものについては、そこに「アンカーファイル」を置いて、ざっくり（数行の）概要を書いてもらう。

- 頭の中にある情報についても、適当なフォルダに「アンカーファイル」を置いて、そのファイルにreSTで情報を記述してもらう。

という対応をお願いすることで、情報やノウハウの集約をし、一覧性を持たせたり、整理することが出来る様になるのでは無いかと期待しています。

４．仕組みを実現するために

アンカーファイルを検索し、.rst化し、sphinxでビルドする為のスクリプトを作成しました。また、日本語検索のためにMeCABも合わせて導入しています。これらの詳細については以下のリンクをご覧下さい。（使い回し.. 汗)

- Sphinx on windows (Admin権限なし版)

- github:AutoBuildSphinxIndexScript_forWindows

５．状況と今後の課題

実はすでに半年ほどこのSphinxによる情報整理に取り組んでおります。事務屋さんな環境において、以下の様な状況になっております。

- 今まで個人資料だったものが集約されて、結構な数のページが生成されている

- いまも週に数ページのペースで増えている

- だんだんと reST 記法が浸透してきている

- 足りない機能が出てきた

- たとえば、.. figure:: の画像ファイル添付などは.rst に変換後にファイルを移動してしまうためにリンクが切れてしまう

- 検索機能は期待したほど助けになってない

- MeCABのユーザ辞書を活用しているが、どうも英数字周りが弱い

- ページ内検索と検索ツールを併用してどうにか見つかる程度

とりあえず、来年まで活用を続けてみて、なにか良い結果になればと思っております。さて、明日は @takanori さんです。

7日目: 異なった環境で Sphinx と blockdiag とかを使う

- 著者: @tananori

- 原文

Sphinx Advent Calendar 2012 の7日目です。昨日は @GoingMyWayNet さんの Sphinx と MeCAB でナレッジベース風ツールを作る | GoingMyWay でした。

おそらくみなさんはたくさんの人でリレーするこのアドベントカレンダーよりも Sphinx Advent Calendar 2012 (全部俺) の方が気になっていると思いますが、少しお付き合いください。

私は今年の9月に成功裏のうちに開催された PyCon JP 2012 の併設イベント SphinxCon JP 2012 で「社内でのSphinx、reSTの広め方」と題して発表をしました。以下が発表資料ですが、ここではその内容のフォローをちょっとしようと思います。

How to spread reST and Sphinx from Takanori Suzuki

Sphinx を使ったことがないチームで、みんなで Sphinx を使って基本設計書を書くことにしました。 Sphinx だけでなく、画面遷移図とかを書くための blockdiag と、シーケンス図を書くための seqdiag も使いました。

先ほどの発表資料の19ページ目で説明したんですが、以下のようなさまざまな環境が混在している状況で、それぞれの人が快適に書けるようにする方法を模索していました。

- Windows(メンバー)/Linux(ドキュメントをbuildするサーバー)

- Sphinx なし/Sphinx のみ/Sphinx + blockdiag + seqdiag

ここで問題になるのは、Sphinx のみの人とSphinx + *diag 環境の人で問題が出なくすることと、Windows 環境と Linux 環境で *diag が正常に動くようにすることでした。

Sphinx のみと *diag ありの切り分け

blockdiag とか使うときは blockdiag ディレクティブを指定しますが、blockdiag が入っていない環境でも警告は出ますがエラーは特に出ません。

.. blockdiag::

blockdiag admin {
top_page -> config -> config_edit -> config_confirm -> top_page;
}

しかし、blockdiag を使用するためには conf.py に以下のように記述する必要があります。

extensions = ['sphinxcontrib.blockdiag']

blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'

この状態で blockdiag が入っていない環境で make html を実行すると以下の様にエラーとなります。

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.1.3

Extension error:
Could not import extension sphinxcontrib.blockdiag (exception: No module named sphinxcontrib.blockdiag)
make: *** [html] Error 1

これを回避するためには、blockdiag があるかどうかを import で調べてから、設定を行うと回避できます。seqdiag も同様に設定すればOKです。

extensions = []
try:
import sphinxcontrib.blockdiag
extensions.append('sphinxcontrib.blockdiag')
blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
except:
pass

Windows 環境と Linux 環境

Windows 環境と Linux 環境で *diag を使用するためには、それぞれの環境で正しいフォントを指定する必要があります。

そこで、python の sys.platform を使って環境の切り分けを行います。あとはここで設定した fontpath を blockdiag_fontpath, seqdiag_fontpath に指定すればOKです。(ここでは Mac にも対応しています)

import sys
if sys.platform == 'win32':
fontpath = 'C:\Windows\Fonts\msmincho.ttc'
elif sys.platform == 'darwin': # Mac
fontpath = '/Library/Fonts/Osaka.ttf'
else: # linux
fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'

(12月13日)追記

blockdiag_fontpath には パス文字列の配列を指定することで環境の違いを吸収することができ るそうなので、上記のようなめんどくさいことはしなくていいようです。:

fontpath = ['C:\Windows\Fonts\msmincho.ttc', # for Windows
'/Library/Fonts/Osaka.ttf', # for Mac OS
'/usr/share/fonts/truetype/ipafont/ipagp.ttf', # for Linux
]

このあたりは実際に会社であーでもないこーでもないとやっていたときに、現会長の @tk0miya さんと現副会長の @shimizukawa さんに教えてもらいました。

明日はその清水川先生の出番です。よろしくおねがいします。

8日目: intersphinxを使おう - #sphinxjp アドベントカレンダー2012

- 著者: @shimizukawa

- 原文

Category: 'Python', 'Sphinx', 'intersphinx'

Sphinx Advent Calendar 2012 8日目担当の清水川です。昨日は @takanory の Sphinx Advent Calendar 7日目: 異なった環境で Sphinx と blockdiag とかを使う でした。

おそらくみなさんはたくさんの人でリレーするこのアドベントカレンダーよりも Sphinx Advent Calendar 2012 (全部俺) の方が気になっていると思いますが、少しお付き合いください。

最近、Sphinx本体のCo-Maintainerになったので、Sphinxの実装コードを読んだり書いたりする機会が多くなりました。その関係でいままで使っていなかった便利な機能に気がついたり、問題解決のためにちょっとした拡張を書けるようになってきました。

で、今回のネタはintersphinxです。

intersphinxの使い方

intersphinxは他のSphinxドキュメントにリンクしやすくする拡張機能です。 Sphinxに同梱されていますが拡張扱いになっているので、conf.pyのextensionsに以下のように追加しないと使えません:

extensions = ['sphinx.ext.intersphinx']

詳しくは公式ドキュメント [1] に書かれているので省略しますが、以下のように使えます。

example.rst:

例1: 詳しくは :py:mod:`sphinx:sphinx.ext.intersphinx` を参照して下さい。

例2: 例えば :ref:`sphinx:domains` にもリンクできます。

conf.py:

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
'sphinx': ('http://sphinx-users.jp/doc11', None),
}

これをmake htmlでビルドすると以下のようにレンダリングされます:

例1: 詳しくは sphinx.ext.intersphinx を参照して下さい。

例2: 例えば Sphinxドメイン にもリンクできます。

ローカルドキュメントにリンクするかのように、外部サイトにリンクしてタイトルも正しく表示出来ましたね。

intersphinxの仕組みとしては、 make html したときに必ず生成される objects.inv を http://sphinx-users.jp/doc11/objects.inv から取ってきてリンクの解決をしています。objects.invはインベントリ(inventory)と呼ばれるファイルで、名前付きのリンクターゲットが保存されています。

Sphinx以外のドキュメントにintersphinxでリンクする

例えばJavaのドキュメントがあったとします。そこに以下のように書いてリンクできると楽だよなーと思うわけです:

外部のJavaのドキュメントに :ref:`javaapi:api1` これでリンクしたい

前述したように、intersphinxを使えば外部へのリンクを内部リンクのようにreSTに記述して生成することができますが、そのデータはobjects.inv等のインベントリを使って実現しています。ということは、それっぽいインベントリを用意出来ればSphinx的にはリンクを作れることになります。

といことで、 javaapi.inv を作ってみました。

# -*- coding: utf-8 -*-

import zlib

inventory_header = u'''\
# Sphinx inventory version 2
# Project: javaapi
# Version: 2.0
# The remainder of this file is compressed with zlib.
'''.encode('utf-8')

inventory_payload = u'''\
api1 std:label -1 api.html#api1 API 1
'''.encode('utf-8')

# inventory_payload lines spec:
#   name domainname:type priority uri dispname
#
# * `name`       -- fully qualified name
# * `domainname` -- sphinx domain name
# * `type`       -- object type specified by domain (ex. label, module)
# * `uri`        -- relative uri with anchor
# * `dispname`   -- name to display when searching/linking
# * `priority`   -- how "important" the object is
#                   (determines placement in search results)
#
#   - 1: default priority (placed before full-text matches)
#   - 0: object is important (placed before default-priority objects)
#   - 2: object is unimportant (placed after full-text matches)
#   - -1: object should not show up in search at all

inventory = inventory_header + zlib.compress(inventory_payload)
open('javaapi.inv','wb').write(inventory)

これを実行すると javaapi.inv が生成されます。inventory_payloadのところでリンク先のデータが定義されているので、ここをどんどん書き足していけば、好きなリンクターゲットを作れるようになります。

作成したjavaapi.invはローカルに置く場合は以下のようにconf.pyを設定します。

conf.py:

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
'sphinx': ('http://sphinx-users.jp/doc11', None),
'javaapi': ('http://api.example.com/', 'javaapi.inv'),
}

リモートサーバーに置く場合は以下のように書きます。objects.invという名前でないのでちょっと長いですね。

conf.py:

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
'sphinx': ('http://sphinx-users.jp/doc11': None),
'javaapi': ('http://api.example.com/',
'http://api.example.com/javaapi.inv'),
}

ノート

domainname:type の部分は :ref: でリンクしたい場合は std:label にします。 :py:func でリンクしたい場合は py:function にします。このあたりはドメインの話なので、詳しくは Sphinxドメイン を参照して下さい。

ドキュメント内にリンクターゲットを作ってintersphinxでリンクする

intersphinxを活用する上で、今のSphinxにはちょっとした問題があります。

Problem

intersphinxのための情報はすべて objects.inv に含まれていますが、ここに無名のリンクターゲットが含まれていません。

例えば index.rst が以下のように書かれているとします:

.. _named-label:

Welcome to spam's documentation!
================================

.. _anon-label:

ham! egg! spam!

これを make html して生成した objects.inv は以下のようになります:

u'std:label': {u'genindex': (u'spam', u'1.0', u'genindex.html#', u'Index'),
u'modindex': (u'spam',
u'1.0',
u'py-modindex.html#',
u'Module Index'),
u'named-label': (u'spam',
u'1.0',
u'index.html#named-label',
u"Welcome to spam's documentation!"),
u'search': (u'spam', u'1.0', u'search.html#', u'Search Page')}

この objects.inv には 'anon-label' が含まれていないため、外部のSphinxからintersphinxを使ってこのラベルにリンクすることが出来ません。

Solution

この問題はいまSphinx本体で解決出来るのでは無いかと提案(#1050, #1052)が行われていますが、とりあえず新しいドメインを作って対処するコードを書いてみました。

AnonimousDomain (ext_anon_domain.py) は全てのラベルをobjects.invに保存します。

先の例に出したindex.rstであれば、objects.invに以下のようにターゲットが保存されます:

u'anon:label': {u'anon-label': (u'spam',
u'1.0',
u'index.html#anon-label',
u'-'),
u'named-label': (u'spam',
u'1.0',
u'index.html#named-label',
u'-')},
u'std:label': {u'genindex': (u'spam', u'1.0', u'genindex.html#', u'Index'),
u'modindex': (u'spam',
u'1.0',
u'py-modindex.html#',
u'Module Index'),
u'named-label': (u'spam',
u'1.0',
u'index.html#named-label',
u"Welcome to spam's documentation!"),
u'search': (u'spam', u'1.0', u'search.html#', u'Search Page')}

実装コードは以下のようになります。

ext_anon_domain.py

conf.py

ただし一つ問題があって、対象のラベルにintersphinxでリンクする時にもこの拡張が必要になります。リンクは以下のように書けます。

無名ラベルへのリンクを :anon:ref:`anon-label` このように書きます。

と言うことで、AnonimousDomainを作ってみましたが、使う方の準備がけっこう面倒くさいですね。他の拡張ドメインを使った場合にも同じ問題は起こるので、このあたりはSphinx本体でなんとかなると嬉しいのかもしれないですね。

最後に

明日は @tcsh さんの回です。@tcshさんにはJUS勉強会でのSphinx発表の場を提供してもらったり、PyConJPで発表してもらったり、色々お世話になっております。明日よろしくおねがいします！

9日目: Sphinxから見えるドキュメント作成の過去、現在、未来

- 著者: @tcsh

- 原文

Sphinx Advent Calendar 2012 9日目担当の 波田野 ( @tcsh ) です。

昨日は @shimizukawa さんの intersphinxを使おう #sphinxjp アドベントカレンダー2012 でした。

たくさんの人でリレーするこのアドベントカレンダーよりも Sphinx Advent Calendar 2012 (全部俺) の方が気になっていると思いますが、こちらもがんばって書きますよ!

追記::

がんばり過ぎて長くなりました。 10人中9人は 最後 まで読み飛ばしそうな勢いです(w

一気に書いたので、あんまり査読もしてないです。スイマセン(^^;

Contents

- 9日目: Sphinxから見えるドキュメント作成の過去、現在、未来

- 出会い

- ドキュメント作成の過去、現在

- ドキュメント作成の過去 (手書き時代)

- ドキュメント作成の過去 (自動化黎明期)

- ドキュメント作成の現在

- なぜ人はドキュメントを書くのか

- ドキュメントの価値

- ドキュメントの利用価値 (利用者視点)

- ドキュメントの提供価値 (提供者視点)

- ドキュメントの構造化 (ドキュメント設計)

- ドキュメント構造化とは

- ドキュメント構造化とSphinx

- Sphinxがもたらすもの

- ドキュメントの未来

- 関連資料

- 最後に

出会い

2010年09月10日-11日に八王子で開催された オープンソースカンファレンス に 運用研究会 として出展したのが、Sphinx と @shimizukawa さんとの出会い でした。運用研究会では 運用にとって最も重要な基盤はドキュメントである と考えていることもあり、ブース説明員清水川さんの腰が引けるほど喰い付き良く喰いついちゃったことを覚えています。

そして、3ヶ月後に ドキュメントを作りたくなってしまう魔法のツール Sphinx の講演(講師は渋川さん、清水川さん、山口さんという豪華講師陣)をしていただきました。この時期以降、 blockdiag の普及とともに非プログラマ系エンジニア(業務系、運用系エンジニア)のみなさんに Sphinxが認知されてきたんじゃないかなぁとおもっています。

ノート

自分にとっても、この2つのイベントが Sphinx生活がはじまるきっかけとなり、今はどっぷりreSTを書いて make html する日々になっています:-)

今回は、なぜそこまでこのドキュメントツール "Sphinx" にはまっているかについて、そもそもドキュメント(文書)作成とはなんぞやという根本的なところから論考してみたいと思います。

ドキュメント作成の過去、現在

ドキュメント作成とはなんぞや、という事を考える前に、ドキュメント作成の過去と現在をふりかえってみました。

ドキュメント作成の過去 (手書き時代)

現存する世界最古のドキュメントは紀元前3300年頃(約5300年前)にシュメール文明で作られた粘土板文書で、データ保管、契約書、公文書、知識の蓄積目的など今日とあまり替わらない用途で使われていたようです。

2世紀頃に中国で紙が発明され、7世紀に木版印刷、15世紀にグーテンブルクによる活版印刷、18世紀末に平板印刷がそれぞれ発明され、(主に出版目的での)定型ドキュメントの紙による大量作成への道筋を付けました。

参考:

- 粘土板 (WiKi Pedia)

- 印刷 (WiKi Pedia)

ノート

ドキュメント作成(編集/出力)のうち、出力技術は18世紀末(約200年前)にはじめて一般化した!

(出版目的以外の)個別ドキュメントを手書き以外で作成する方法は、19世紀後半(約150年前)にタイプライターが出現したのがおそらく最初でしょう。

タイプライターには挿入削除という概念は無く、ミスをすると最初から全て入力しなおしでした。ドキュメント入力後に挿入削除を含む "編集" ができるようになるのは一般的には20世紀末、個人向けワープロやパーソナルコンピュータが普及してからと考えて良いでしょう。

参考:

- タイプライター (WiKi Pedia)

ノート

ドキュメント作成(編集/出力)のうち、編集技術は20世紀末(約20年前)にはじめて(出版目的以外で)一般化した!

「編集」「出力」というドキュメント作成の両輪が手元に揃った1990年代以降、急速に作成されるドキュメントの量は増えていきます。ただし、単に手書き(もしくはタイプライター)のアウトプット(印刷)が電子化されて編集や再利用可能となったのみで、人々は、一太郎、Word、Excel、PowerPoint やHTMLオーサリングツールなど数多あるツールとキーボードというデバイスを通じて手で書いていました。

あくまでもドキュメントを作成/編集するのは人間だったのです。

警告

一部、先進的な人々は、技術文書を中心に roff や TeX などで、人が手で書いたものを、機械(システム)が編集/変換してくれるようにしてきました。

(SGMLは...)

ドキュメント作成の過去 (自動化黎明期)

この状況に劇的な変化を与えたのが、2000年代初頭に爆発的に普及した XML および 周辺技術を使ったマッシュアップ、その上位概念としての "セマンティックWeb" だったと思います。

セマンティックWebにより、ドキュメントの各要素の全てを必ずしも自分で作る必要がなく、公開されているドキュメント要素を引用し、加工し、かつ人間だけなく機械がドキュメントをコンテキストや条件に従い自動生成するようになってきました。

ノート

ドキュメント作成(編集/出力)のうち、出力技術は21世紀(約10年前)に自動処理が一般化した!

いよいよドキュメント作成(編集/出力)に機械が参画するようになってきたのです。

ドキュメント作成の現在

Ajaxなどのドキュメントをマッシュアップする技術が普通に使われるようになった現在、肥大化した (XPathなどを含む)XML系技術に対して、アンチテーゼとして、誰でも気軽に使えるドキュメントフォーマットがいくつか出てきました。

1. XMLの複雑さを回避するもの

2. 人の可読性を重視するもの

1の代表的な例として JSON、2の代表的な例としてRubyコミュニティでよく使われている YAML (Yet Another Markup Language) が、Pythonコミュニティでよく使われている reST (reSTructured text) がある、と自分は認識しています。XMLを含むこれらのドキュメントフォーマットにより記述されたドキュメントは、それぞれの記法に従って構造情報を文書内に記述することから、 "構造化ドキュメント" と言われます。

今日(主観的に)よく使われている構造化ドキュメントとパーサーの組み合わせとしては、下記があると思います。

構造化ドキュメントとパーサーの組み合わせ例

- HTML + ブラウザ

- XML + XMLパーサ

- JSON + JSONパーサ

- YAML + YAMLパーサ

- reST + docutiles/Sphinx

これらパーサの多くは、パースの際に指定することで出力結果を変えることができます。人が書いた1つの構造化ドキュメントを、機械が適宜フォーマットにあわせて加工した上で出力してくれるようになってきたのです。

ノート

構造化記法の選択肢が増えてきた。1ソース マルチアウトプット という考え方が出てきた。

(特にSphinx は手元(デスクトップなど)で手軽に実現できる。)

ドキュメント作成における「編集」「出力」の両輪のうち、「出力」については機械が適宜やってくれる時代になりました。となると、次はドキュメント「編集(記述や推敲を含む)」をどう機械にやらせるか、が次の大きなトピックとなるでしょう。

構造化されたドキュメントでは、全てを人が手で記述する必要は無く、人の手によらなければ作ることができない「主観ドキュメント」のセグメントと、システマティックに生成されるべき「客観ドキュメント」のセグメントを明確に分離し、それらをセマンティックな技術で編集することで、より軽い手間で、より正確で、より最新の情報を盛り込んだドキュメントを作ることが可能になるはずなのです。

ノート

ドキュメント作成(編集/出力)のうち、編集技術は21世紀第1四半世紀(これから10年くらい)で自動処理が急激に一般化するはず (だと思う)

人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージにきているのです。(たぶん)

なぜ人はドキュメントを書くのか

ドキュメント作成について、今後は構造化を意識して、なるべく人が手を下さずに書きましょう と、いう前項の結論を受けて、じゃそもそもドキュメントを人はなぜ必要とするのか、という話題に入ります。

必要とされないのであればそのドキュメント(とその自動生成)に工数を掛ける意味がないので、これは重要な論点です。

ほとんど場合、下記の4つのいずれかの必要性(目的)からドキュメントが作成されます。

ドキュメントの必要性(目的)レベル

- Level-0: 「記録のために」(ドキュメントの本質的な機能)

- Level-1: 「整理のために」

- Level-2: 「客観化のために」

- Level-3: 「脱属人化(普遍化)のために」

参考:

- 運用ドキュメントが必要な理由

このうち、Level-3は人間の領域です。そうじゃないと人間の存在価値に疑問符がついちゃうので、そう考えています。一方で、Level-2以下は、全て自動化が可能とは思いませんが、レベルが低いほど、機械が担当する割合が高い領域だと考えています。

ノート

各ドキュメント作成の必要性をまず明確にしよう。 (必要性の低いドキュメントに工数を取られないようにする)

その上で、そのドキュメントの必要性(目的)を明確にし、どの程度の割合で人と機械がドキュメント作成を分担するか決める。 (そんな時代がたぶん来る)

ドキュメントの価値

さて、人と機械がドキュメント作成を分担することとして、どの部分を人が書き、どの部分を機械に書かせるべきでしょうか。一義的には、一定の規則性に基いてシステマティックに生成できるドキュメントは機械が書き、そうではないものは人が書くべきでしょう。正論です。 ただ、それではいつまでたっても人が書くドキュメントは減りません。

今後は視点を変えて、人は「人が作成することで費用対効果が大きいことが期待できるドキュメント」を作成し、そうではない「人が作成すると費用対効果が見合わないドキュメント」は機械に作成させる流れになるでしょう。

警告

極論すると、「機械が作成しても費用対効果が見合わないドキュメント」は「作らない」ことになるでしょう。

では、そのための判断基準はどんなものになるのか? それは各ドキュメントの最大のステークスホルダーである「ドキュメントの利用者」と「ドキュメントの提供者」の視点からの2つの「価値」基準になると考えています。

2つの「ドキュメントの価値基準」

- ドキュメントの利用価値 (利用者視点)

- ドキュメントの提供価値 (提供者視点)

ドキュメントの利用価値 (利用者視点)

まず、利用者視点で「ドキュメントの利用価値」が存在しないといけません。利用者の利用価値の無いドキュメントは、作成維持する意味がないからです。

仮に利用者が(たとえ自分ひとりであっても)存在するのであれば、「いかに使われるか」という観点から、下記の3つの評価ベンチマークでその価値を評価できると考えています。

ドキュメントの利用価値ベンチマーク

1. 読者の範囲

- 水平方向: 社会的範囲 (特定現場 〜 不特定多数)

- 垂直方向: 社会的地位 (専門層/経営層 〜 一般層)

2. 参照回数

3. 利用期間(寿命)

1の「読者の範囲」は外的要素による影響が大きいため、ここでは「参照回数」、「利用期間」の2つを最大化させるためには何が必要か考えてみます。

反復利用できること (可用性 Availability)

- 使いたい時に使える(反復利用できる)状態になってはじめて利用価値が生まれます。

- 使いたいときにドキュメントを利用できないことで、利用価値が低減します。

- 「可用性」は機械に担保させるべき領域だと考えています。

内容が信頼できること (信頼性 Reliability)

- 内容の間違いが最小限である(最新を維持する)ことで利用価値(信頼)が高まります。

- 古い、誤りがある、などドキュメントが信頼できないことで、利用価値が低減します。

利用機会を増大できること (保守性 Serviceability)

- 再利用性を高め、ドキュメント数を増幅させることで、読者の利用機会を増大させることが可能となります。

- ドキュメントの維持保守ができない(提供機会の増大どころではない)と、利用価値が大きく低減します。

これら3要素は、直接間接的に参照回数、利用期間に影響し、そのドキュメントの最終利用価値を増加/低減させます。

このうち「ドキュメントの利用価値」の本質とも言うべき「信頼性」「保守性」については、各情報の要素は機械が生成し、その情報に対する意味づけやドキュメントの幹となる部分は人が書くことで維持拡大していくことになるでしょう。そしてその手法として、「利用価値のためのドキュメンテーションデザインパターン」と言うべきものが徐々に形作られていくのではないかと考えています。

参考:

- 運用ドキュメントの利用価値 評価ベンチマーク

ノート

- 繰り返し使われ、寿命が長いほどドキュメントの利用価値は高い。

- その利用価値は「機械が各情報の要素を生成と整合性を確保し、人が意味付けや幹を作る」という分担により「ドキュメントが常に最新で正確である」ことを保つことで維持拡大する (というイメージ)

ドキュメントの提供価値 (提供者視点)

さて、利用価値が有意であると見込まれるのであれば、提供者側はドキュメントを作成しなくてはいけません。しかし、ドキュメント提供側でも、そのドキュメントの作成維持に無限のリソースを使用することはできないため、そのドキュメントの提供に関わる費用対効果が問われることになります。

その費用対効果は、反復利用、再利用性の高さと、陳腐化の早さに着目し、資産性、費用性を評価することで判断できると考えています。

ここは長くなるので、詳細は下記の "参考" に譲りますが、「費用性ドキュメント」は機械に作らせて、人は「資産性ドキュメント」や「収益性ドキュメント」など 費用対効果が適切に見こめるドキュメントの作成 に持てる限りのリソースを注ぐことになるでしょう。

参考:

- 運用ドキュメントの提供価値 (費用対効果)

- SCA分析 (仮称)

ノート

- ドキュメントの提供価値は、そのドキュメントのテーマによる資産性(プラス)/費用性(マイナス)によって大きく影響を受ける。

- 仮に会計的にこれらを分析した場合、「費用性ドキュメント」を人が作成した場合の費用対効果は、直接配賦ができない限りは「費用のみ存在」し「効果はゼロ」であり、「資産性ドキュメント」もしくは「収益性ドキュメント」を書かない限り、ドキュメント陳腐化の早さもあり、ドキュメント提供に対する費用対効果はプラス方向に行かない、ということになります。(あくまでも比喩ですが)

ドキュメントの構造化 (ドキュメント設計)

各ドキュメントの提供価値が明確になった(まだ難しい?)ところで、ようやくそのドキュメントの設計に着手します。はい、ドキュメントの構造設計です。構造化ドキュメントを書く上では避けられない部分ですね。

ドキュメント構造化とは

今回の論考では、「構造化」を下記の通り定義します。

構造化とは

「ばらばらになっているものを、一定の基準に従い論理立てて整理すること」

そして、ドキュメント構造は概ね、下記の3つの基本要素で構成されています。

基本要素1. 見出し

文章ブロック単位での意味付け (単位情報のオブジェクト化)

基本要素2. 目次

読み手が認識しやすい位置への文章ブロックの格納 (ツリー構造(多分木)による構造表現化)

基本要素3. クロスリファレンス

文章ブロック間の関係付け (情報間ネットワーク構造の表現化)

ここも長くなるので詳細は下記に譲ります(笑

参考:

- ドキュメントの構造化

ドキュメント構造化とSphinx

勘の良い人であればすぐに気付いたと思いますが、前項の「ドキュメントの基本要素」3つを比較的自然かつ平易な記法で構造化できるのが Sphinx の利用を前提とした reST (reSTructured Text) です。

繰り返しいろいろな人に言いまくっているのですが、Sphinx(reST)の特筆すべき特徴は 普通のテキストに見えるのに、比較的違和感を与えないままに構造化ドキュメントにすることができる!! これは、現時点では他の構造化記法にはない特徴です。

警告

定型メールなど短い定型書式などでは、YAMLの方が自然だと思います。

Sphinx においては、ドキュメントの基本要素3点を下記の通り記述できます。

基本要素1. 見出し (reST標準)

Section Structure(同一記号を見出しの下に連続して記述) で極めて自然に実現しています。

基本要素2. 目次 (Sphinx拡張)

toctree でドキュメント全体のツリー構造化を実現しています。(管理もしているそうです)。記法は自然とは言い難いですが、マッチングによる自動処理(:glob:)などを比較的平易な書式で利用可能です。

基本要素3. クロスリファレンス (Sphinx拡張)

ラベルと解釈済みテキストロール(ref)を組み合わせて、これまた比較的平易な書式で記述可能です。記法は自然とは言い難いですが、その特性上、あまり目立たないところに記述されることが多いので、そんなに邪魔にはならないかなとおもっています。

ノート

特に、クロスリファレンスが非常に簡単に利用できる点を個人的に高く評価しています。

Sphinx(reST) は、「普通のテキストっぽいのに構造化されたドキュメント」を書くことも、「ばりばりに構造化されたドキュメント」を書くこともできるのです。これは構造化ドキュメントを書くための敷居を大幅に下げる効果があります。なぜなら、やれる範囲で構造化しておいて、必要が出てきたときに後で直すことが容易にできる、かつやればやるだけその効果があるからです。

Sphinxがもたらすもの

ドキュメントの構造化には、抽象化能力が人にもドキュメントツールにも強く求められると考えています。

人に求められる「抽象化能力」とは、"対象から注目すべき要素を重点的に抜き出し、他は無視する手法を適切に使いこなす能力"で、ドキュメンテーションでは非常に重要な能力です。なぜなら、全ての事象をドキュメントに記述することは事実上不可能であり、なんらかの取捨選択をした上で、効率的かつ理解しやすい形でドキュメントにまとめあげていかなければならないからです。

ドキュメントツールに求められる「抽象化能力」とは、1つは機能や操作に特徴的な側面を取り出して扱いやすく提供すること、もう1つはその機能や操作において物理的な制約を内包せずに論理的な構造に常に追随すること、と個人的には捉えています。

ここでは、この定義に従い、Sphinxがもたらす抽象化のメリットを列挙してみます。

ノート

- 相対化と言うべきものも一部もありますが、ここでは無理に分類しません。

- 「Sphinxのここが残念だよ問題」も思い出せる範囲で書いてみます。

見出しの指定

コンテキストによって自動的にレベルを判断してくれる

- ただし、include 先のドキュメントに見出しがあると、include元の見出しとコンフリクトする。これがかなり残念 (Section Structure 衝突問題)

クロスリファレンスの指定

リファレンス先のラベルとリファレンス元のrefロールは、指定されているラベル名が同一であれば、それぞれは同期を意識する必要がなく、ファイル構成が変更されてもbuildしなおせば自動的に追随してくれる。ドキュメント上にネットワーク構造を構築するのが非常に容易で、秀逸。

- リファレンス先として集中しているところが「情報の重心」のひとつになるはずだが、現状では標準のSphinxでクロスリファレンスの構成やラベルが重複しないように管理する機構がユーザには提供されていない。 (toctree見える化問題)

コンテンツの共通部品化(includeやliteralinclude)

インクルード先のドキュメントがreSTであればパースしてくれる。

- ただし、include指定はパス指定なので、ファイル構造を変更すると大崩壊する。 (include 抽象化問題)

- refロール同様に、ファイル構造が変更されても自動的に追随するような include がほしい。(ファイル単位のラベルって概念が必要そうだけど)

- 多段includeすると、全てincludeの大元ファイルからのパスを見るので、普通にやると失敗する。 (多段 include ができない問題)

- たしか、1.0.7 くらいまでの literalinclude では多重インクルードができたので、復活させてほしい。

- 特に階層的に構造化したい場合は必須なので。

InterSphinx

まだつかったことない のですが、複数のSphinxドキュメントの境界を意識しなくて良くなる野心的な機能だと思っています。

- 現状ではリンクのみ可能ということで、interincludeを是非実装していただきたい、と思っています。 (InterInclude 実装要望)

- InterIncludeが実現されると、Sphinxで作成して成長したドキュメントを好きなタイミングで分割する自由が得られるはず、なので。(ドキュメント分家方式の実現)

ドキュメントの未来

ドキュメントの今後を考える上で、作成工数の抑制と効率的な維持管理を実現するための「システマティックなドキュメント生成」という視点は極めて重要になっていくと思います。そして、セマンティック技術の再評価、情報の「マッシュアップ」技法など、IT技術によるIT技術現場のためのドキュメント技術の実践拡大に非常に期待を持っています。

その実践技術の一つとして Sphinx が非常に有望な位置に今いると思うのです。

今後ドキュメントというものは、人がWhyを主体的に書き、機械が4W1H(What/When/Where/Who/How)のほとんどを与えられたコンテキストを元に記述していくことになると思います。そして人と機械が書いたものが、マッシュアップされることを前提にドキュメンテーションという活動は成立していくのだろうと考えています。更に、業務自体はドキュメントドリブンという、本来あるべき姿で動いていくのだろうと思います。

くりかえしになりますが、人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージに今きているのです。(そんな実践をしている人がいれば飛んで話を聞きにいきたい今日この頃)

ノート

ドキュメント作成(編集/出力)のうち、編集技術は21世紀第1四半世紀(これから10年くらい)で自動処理が急激に一般化するはず (だと思う、と繰り返してみる)

関連資料

- 運用ドキュメント2011～手軽にスピーディに継続的に保守するためのツール入門～ (Internet Week 2011 / 2011年11月)

- 清水川さんとの共同セッション。Sphinxが主要テーマの一つでした。

- 当日の プレゼンテーション資料 も公開されています。

- Operation Document Model (2012-01-09 LastUpdate)

- 今回の記事で引用しまくっていますが、自分なりに今年の年初にまとめたメモです。

- Sphinx Advent Calendar 2012 6日目の記事 Sphinx と MeCAB でナレッジベース風ツールを作る (GoingMyNetさん)の記事中で言及いただきました! さんきゅ!

- 運用ドキュメントの分類と構造化 (電子情報通信学会 インターネットアーキテクチャ研究会 2011年度第6回研究会 / 2012年1月)

- Sphinxを念頭に運用ドキュメントの構造化について論文発表しました。

最後に

いやー長かったですね(笑。ちゃんと読んだ人が10人でもいれば大満足です。機会があればコメントください(^_^。

明日は Sphinx Advent Calendar 2012 (全部俺) の @usaturn さんです。

自分と似た環境(Sphinx初心者&プログラマーではない&インフラ出身)の方の発表なので、ものすごく楽しみです!

10日目: 本家 Sphinx Advent Calendar 2012 10日目 ～サクラエディタから make html～

- 著者: @usaturn

- 原文

9日目の 波田野さん ( @tcsh )から受け取りました。

ドキュメント作成の歴史を紐解きながら、ドキュメントの構造化～システマティックなドキュメント作成への期待を語られていて興味深く感じました。

さて 本家 Sphinx Advent Calendar 2012 の10日目です。全部俺版とは別に投稿したいと思います。

サクラエディタとマクロ

最近では Vim や Sublime Text 2 、 Emacs だとかが流行っているらしいですが、Windows使ってるなら サクラエディタ でしょう。

仕事柄、色々な現場に入るのですが、どこでも サクラエディタ は必ず使われています。かくいう私も10年程 サクラエディタ を使っておりました。 第3日目 Sphinxドキュメントを書く道具 も参照して頂けると幸いです。

この サクラエディタ 、マクロが PPA と WSHが使えます。詳しくは こちらへ

makeからブラウザ確認までを1動作で

- タイトルの通りです。サクラエディタで編集する際に 編集 -> make html -> ブラウザを起動して確認 ..... というサイクルの手間を少し省く事ができます。

使い方

1. これ をダウンロードし、任意のディレクトリに配置します。

例:

C:\tools\Editor\macro\build_and_browsing.vbs

2. 設定 -> 共通設定 -> マクロ タブにて マクロ一覧 にマクロを配置したディレクトリを指定します。

3. マクロの登録一覧の空欄の部分を選択します。初めて登録するならば 0 を選択しましょう。

4. 名前 に任意の名前を付けます。とりあえず make html としておきましょう。

5. File にてドロップダウンメニューからマクロのファイルを選択します。

6. 設定 をクリックします。

7. キー割り当て タブをクリックします。

8. 種別 を 外部マクロ にします。

9. make html をクリックします。

10. 任意のキーを割付して下さい。

例 Alt + B を設定する場合

1. Alt にチェックを入れる

2. キー欄をスクロールして Alt+B をクリック

3. 割付 を押下します。

4. 機能に割り当てられているキー に Alt+B が、 機能に割り当てられている機能 に make html が表示されている事を確認し OK をクリックします。

11. プロジェクト 内のreSTファイルをサクラエディタで開き、おもむろに割付したキー(例では Alt+B )を押しましょう。

12. make html の結果がポップアップされ、編集している reSTファイル のhtmlがWebブラウザで開かれれば成功です。

マクロの中身

さ～て、明日のSphinxアドベントカレンダーは？

- 明日は @grimroseさん が 担当 です。手順書を作成した時の過程を書かれるそうです。楽しみですね！

11日目: Sphinxで手順書を作ってみませんか？

- 著者: @grimrose

- 原文

このエントリは Sphinx Advent Calendar 2012 の11日目のエントリです。 10日目のエントリは @usatarn さんの 本家 Sphinx Advent Calendar 2012 10日目 です。

はじめに

なぜ、普段JavaやGroovyしか書いていない私が、このAdvent Calendarに参加したのかは、@usatarnさんとの以下のやり取りでした。

#sphinxjp の人からconnpassのページを開けと言われるがままに開いたら今度はボタンを押せとか言われました。気付いたら「Sphinx Advent Calendar2012」に強制参加させられていたので皆さんも宜しく！いやあSphinxの人こわいわ～ #pyfes

— うさたーんさん (@usaturn) 11月 24,2012

@usaturn 頑張ってください。

— とーますさん (@grimrose) 11月 24, 2012

@grimrose 一緒にやりましょう！

— うさたーんさん (@usaturn) 11月 24, 2012

@grimrose えっ

— うさたーんさん (@usaturn) 11月 24, 2012

まぁ、ネタがなかった訳ではなかったので、参加しました。

おお、参加ありがとうございます！ #sphinxjp RT @grimrose @usaturn え？

— うさたーんさん (@usaturn) 11月 24, 2012

というわけで、よろしくお願いします。

導入経緯

いわゆる手順書を作ったことがある方が、どれくらいいらっしゃるのか分かりませんが、マイクロソフト謹製のオフィススイートで何らかの手順書を作られた方は、だいぶいらっしゃると思われます。

そんなあなたにSphinxで手順書を作ってみましょうというお誘いです。

今回は、ミドルウェアのインストールの手順を書いた時のことを書いてみます。

手順書を作成する時に使ったのは、以下のツールです。

- Sublime Text 2

- FireFox or Chrome + auto reload系のプラグイン

- 10秒ごとに「make html」するpythonスクリプト

- pythonスクリプトを実行するbatファイル

初めてpythonで書いたのは、このスクリプトでした。

動いたっぽい。 import time,oswhile True:os.system("make html")time.sleep(10)

— とーますさん (@grimrose) 10月 24, 2012

全くpythonを知らなかった私に教えて下さった@wonderful_panda さん、ありがとうございました。

もちろんSphinxのインストールは、 Sphinxのインストール を参考にさせていただきました。 Windowsへのインストールは、本当に簡単でした。

準備は、これだけです。

あとは、実際の手順をメモしたり、実行したコマンドをコピーしたテキストなりを開いておきながら、手順書の体裁を整えて行きました。

メリット

Sphinxでのメリットは以下の点が、メリットではないかなと考えます。

- rstなので、ソース管理できる。

- コードブロックが使えるので、コピペする場合に見た目が分かりやすい

- 標準のテーマのhtmlであれば、別途readerが要らない

reStructredTextのフォーマットに従っていれば、それなりにテーマに沿った形で後で出力してくれるので、書くときは、書きたいことに専念できます。

手順書は後々に、設定が変更になった場合、以前に書かれていたことが分からないと「なぜこのような設定になった」のかが見えにくくなります。しかし、reStructredTextは、テキストベースなので差分管理をバージョン管理システムに任せることができます。バイナリでしか管理できない某ファイルで悔しい思いをした人は、いっぱいいらっしゃると思われます。

Sphinxには、コードブロックが使えるので、コードをそのまま埋め込むことができます。また、シンタックスハイライトを指定できるので、より見やすく出来るようになります。

マイクロソフト謹製のオフィススイートがインストールされてない環境(インストールされてない場合、大抵オフライン環境なのでViewerも落とせません…)であっても、htmlに吐き出せるので、最低限ブラウザさえあれば閲覧可能です。

改善点

初めてSphinxに触ったので、以下の点にちょっと困りました。

- pdfで出力してみたら、ちょっと残念な結果に。

- 表示対象のコードがどのコードブロックの属性にすればいいのか、探すのに苦労した。

後半になってPDFでも出して見ようとしてみたら、レイアウトが崩れたり、コードブロックのシンタックスハイライトがうまく設定されていなかったりと、いろいろ残念なことになってしまってしまいました。もしかしたら、初めからPDFで出力するようにしておけば、もっといい結果になったと思います。

コードブロックの属性については、 http://pygments.org/docs/lexers/ を参考にさせていただきました。これを見つけてからは、いろいろなコードを埋め込める様になりました。

おわりに

私がおすすめするやり方は、以下の手順です、

1. まず普段定型的に行ってる作業の手順を、Sphinxで書いてみる。

2. 次に、DVCSと組み合わせて、差分管理してみる。

そうすれば、マニュアルの引継ぎも変更履歴が追えるので楽になると思います。

まだ、私自身Sphinxを使い始めたばかりなのですが、いろいろなプラグインがあるみたいなので、試しつつ普段の仕事に役に立てばいいなと考えています。

というわけで、うまくお誘いできているか分かりませんが、ちょっとでも興味を持っていただければ、幸いです。

次は、@shibuさんの Sphinx-Users.jpを作った時のお話 です。よろしくお願いします。

12日目: Sphinx-Users.jpを作った時のお話

- 著者: @shibu

- 原文

缶切りでツナ缶を開けようとしたら、缶切りの方が耐久度が低くて壊れたり、パン粉を作るためにプラスチック製のおろし金でパンをすりおろしたら、おろし金の方が削られてツルツルになってしまうような修羅の国アメリカで仕事しています。

僕が日本にいたときに設立したSphinx-Users.jpは代表が変わったあともMLで活発な議論が行われたり、イベントが定期開催されたり、うまく離陸して活動が継続しています。また、当初のもくろみ通りに、単にツールの使い方だけではなく、ドキュメントとは何か？どう書くべきか？ということを考えて発表してくれる人も増えています。

Sphinxのアドベントカレンダーということで、コミュニティについて話をします。easy_installしましょうとかは書きません。Sphinx-Users.jpを作る上で考えたことを思い出しながら書いてみます。

- 2009/04: Vに勧められてSphinxを触り始めて気に入りドキュメントを翻訳

- 2009/09: ドメイン取得

- 2009/11: Sphinx-Users.jpのMLにミッション・ステートメントを決めようとメールを投稿

- 2010/01: 清水川さんがエキスパートPythonの目次だけSphinxで日本語訳を作って公開したらはてブが400を超えて翻訳が決まる事件

- 2010/02: 毎月第二火曜日PM10:00から1時間のスタッフミーティング開始

- 2010/07: 集まってオフ会しましょうかと思ったら、偶然その日に1.0がリリースされて急遽世界最速リリースパーティー開催事件

- 2011/12: 総会で世界の小宮が代表に

コミュニティを作る上でまず考えたのがスコープ。オープンソースのコミュニティというとツールを作るコミュニティもあれば、使うユーザのコミュニティも、翻訳のコミュニティもあったりします。ここではツールを使うコミュニティにしたいと考えました。アート・オブ・コミュニティの日本語訳が出版されたのは2011年の4月ですが、翻訳権が取れる前に自主的に翻訳をし始めていて、その2章の組織のスタートアップの章は参考にしました。スタッフMLにも日本語訳を投下しました。

コミュニティづくりはゲームづくり

コミュニティ運営はゲームづくりだと思います。「ゲームばっかりしてないで勉強しなさい」という呪いの言葉を膝に受けてしまってな、という人はたくさんいると思います。なぜ将来の役に立つ勉強はヤル気が起きないのに、ゲームは「やめろ」と言われてもやりたくなってしまうのか。ゲームの面白さの構造についてはオライリーから翻訳も出ている、「おもしろい」のゲームデザイン ―楽しいゲームを作る理論で書かれています。自炊したはずがPDFがどっかに行ってしまって電子版も買えないのでうろ覚えですが、こんなことを言っていたと思います。

- ユーザに適度な高さのハードルを提供

- ユーザが試行錯誤や学習を行い、なんとかハードルをクリア

- ユーザが満足感を得る

基本はこれの繰り返しとのこと。Sphinx-Users.jpはSphinxを題材にしているので、最初のゴールはSphinxを利用してみることです。インストールの方法、チュートリアル、リファレンス、困ったときに質問できるML、Twitterのハッシュタグ、Sphinx翻訳ハッカソンという勉強会が道具として提供されています。これを見ながらドキュメントをビルドしてみます。おめでとう！不思議な色のHTMLができましたね！これがSphinx-Users.jpが提供するゲームです。ゲームの得意な人はリファレンスだけでなんとかなるかもしれませんし、経験値がまだちょっと足りない人は他の素材も使ってクリアするかもしれません。Sphinx-Users.jp以前は「英語のリファレンスを辞書を引きながら使ってみる」というハード設定のゲームでした。ヒントが増えることで、より多くの人が楽しめるようになりました。

ゲーム的なしくみや、ハードルを下げるコツはこれ以外にもちょっと仕込んであります。オフ会を定期開催することで顔を合わせるようにしたり、会則で定めている「総会」がわざと忘年会と同時開催しやすい12月に設定されていたりとか・・・継続させるための仕組みづくりですね。総会を忘年会と一緒に、というのはインラインスケートの光が丘パイロンズからアイディアを拝借してます。あとは、組織の正式名称とURLを同じにする、組織の略称とハッシュタグを一緒にする、などです。

ゲーム作成者とゲームプレイヤーは対等ではない

アート・オブ・コミュニティでもいろいろ書かれていますが、会社組織とは異なって給料を貰えるわけではないので、魅力があってヤル気にならなければ参加してもらえません。参加だけならまだしも、コミットメントしてもらって1人ではできないことをしようとするとヤル気パルスで他の人のエネルギーをコミュニティに注入してもらう必要があります。

少なくとも、コミュニティ運営とコミュニティ参加は対等ではないと思っています。翻訳をするのに「一緒に翻訳しましょう」と人を集めるケースもありますが、進行管理などは頑張る必要があります。自分が頑張らないでみんなで労働をわかちあいましょう、みたいなのはよっぽど対象が魅力的でなければ回らないと思いますし、「魅力を伝えるために翻訳しましょう」ではニワトリ・タマゴですよね。今回は、Sphinxのドキュメントの最初の翻訳は一人でやり切りました。上下関係がないフラットな民主的・共産的なコミュニティというのはほぼありえないと思います。ディズニーランドでキャストとして成功する人は「チップとデールと友だちになりたい！」みたいな魔法にかかった人だけど、オリエンタルランドとして土台を作っていく人は冷静な目で他の人に魔法をかける(自分はかからない)人という話を人から聞いたことがあります。まあ本当か嘘かはわかりませんが・・・

最初にコミュニティを作ることを考えてから、実際にウェブサイトにコンテンツが乗って動き出すまでにほぼ1年かかっています。もちろん、フルタイムでこの活動だけをしているわけではない、というのもありますし、ある程度コンテンツがそろって、枠組みができあがって・・・ここでゲームができました。中には「ゲームを作るところもオープンでやればいいじゃない」と思う人がいるかもしれませんが、それはよっぽど信用貯金が溜まっている人だけしかできない技だと思います。オープンソースの活動もそうですが、ある程度動くものを提供しないとムーブメントに起きません。あのGoogleでさえ、Noopとは何だったのか、みたいなこともあります。動くものがあれば確実にムーブメントが起きるわけではないですので(誰もコミットもダウンロードもしてくれない僕の作ったツールとかWaveとか)、「ある程度そろっている」ことが十分条件ではないですが、必要条件であると言えます。

日々の仕事もゲームづくり

日々の仕事もある意味ゲームづくりです。ゲームのプレイヤー(モチベーションを喚起されて、働く側)の人もいるかもしれませんが、大事なことは「仕事の流れを作る」人になることです。プレイヤーではなくて、ゲームマスター側になる人になったほうが、選択肢が格段に広がります。これはホンダのフィロソフィーにも書かれていることですね。

例えば、ユニットテストや継続的インテグレーション。赤くなったり、エラーが出ると「直さなきゃ」という気になります。今年のXP祭りのビデオレターでも話をしましたが、アジャイルにはこのようなやる気のスイッチをオンする仕組みがいろいろあります。ソフトウェアも作り方によっては、正しいワークフローから外れた方法をついやっちゃうツールとかも作れてしまいますし、最短のワークフローを歩きやすくするガイドとなりえるケースもありえます。ソフトウェアを作るプロセス、ソフトウェア自身の両方ともがゲームの要素を持っています。

アジャイル開発の場合、ツールの方向性をどうするかは顧客のプロダクトオーナーの采配次第です。スモールリリースや計画ゲームなどは顧客がその部分を学習してステップアップするゲームといえます。現在は社内開発で、自分でコードを書きながら、ユーザが楽しんで成果を出してくれるようなワークフローを考えるような開発をしています。ここまでドップリしているとアジャイルでもなんでもないのですが、いろいろ試行錯誤して良い物を作っていくプロセスはとても楽しいです。最強のゲームですね。アサシン クリードIII も、僕の普段の仕事の楽しさにはかないません。冗談はおいといて、ゲーミフィケーションとかレベルデザインとか、アジャイルとか、そういうのはすべて一つになっていくんじゃないかな、と考えています。

組織論におけるクソゲー

ブラック企業はある意味組織におけるクソゲーかもしれませんが、ミッションがずれているとかおかしいということでブラック企業と呼ばれているものってそんなにない気がします。そもそも人が集まらないですし、持続しませんからね。組織をゲームとして考えた時にどのような組織がクソゲーなのか考えてみたいと思います。

- ゲームとして考えた時にハードル(ノルマ)がやたら高い

- 逆に単調すぎてメリハリがまったくない

- 努力が成果に一切結びつかず乱数で結果が決まる

- もしくは結果がすでに決まっている

- ハードルをクリアしたときの爽快感・ご褒美がしょぼすぎる

- そもそもゴールがゲームマスターの気まぐれすぎる

- ゲームのゴールと違う方向の努力が要求される

- テンポが悪かったり、ロード時間が長い

うまく回っていないコミュニティには何かしらクソゲーの要素が含まれている気がします。逆にクソゲー要素を丹念につぶしていけば良い組織になりそうな気がします。日々の仕事を改善するには、昭和の大成功した人の自己啓発本を読むよりも、クソゲーを学ぶ方が役に立つはずです。畑村さんの失敗学に続く、クソゲー学みたいな学問の誕生が待たれます。

会社という組織のゲーム

コミュニティの考え方は、会社という組織でも基本は同じかと思います。ハードルを提供し、みんなでそれをクリアしてもらう。クリアした時に会社が得られるリソースを使ってさらに高いハードルを提供する・・・と。お金がもらえたとしても社員のモチベーションがあるのと無いのでは成果が段違いです。仕組みが間違っていて「チャンレンジしないでミスもしないのが得」というルールになっていれば、当然組織がそちらの方向に流れていきます。今日、ちょうどRTしたツイートも、会社のゲームのルール次第で組織の性格がどう影響するかを端的に語っています:

@natsutan
日本陸軍の評価は奪った陣地で決まって、出した損害はマイナスにカウントされないんだな。
陣地が奪えない時は、各隊や司令部がどれだけ前進したかが評価になる。だから、無謀な突撃命令がでる。
2012年12月11日

「人を救う仕事がしたい」とか「インフラを支える仕事がしたい」みたいなのがありますが、これはゲームにおけるストーリー・世界観とほぼ一緒かな、と思います。「『おもしろい』のゲームデザイン」でもテトリスに「囚人を効率良くサツガイするために、隙間なく消毒室に並べる」というバックグラインドストーリーを与えたら面白さはどう変わるのか？中身は一切変わらないはずだがどうか？みたいな話がありました。日々やっている作業が同じでも、業種が違うとヤル気になる人が出たり出なかったり・・・働く人は自分のモチベーションが高められて、良いパフォーマンスが出せる会社を選ぶのがゲームの勝利の鍵です。コミュニティの「ミッション・ステートメント」はこのバックグラウンドストーリーにあたる部分です。コミュニティづくりを考えている人は、アート・オブ・コミュニティの2章もしくは、それの実践例を見ながらここをじっくり作るのをオススメします。

上記のクソゲーの要素は会社にも当てはまると思います。ただし、会社組織で必要になるのが「人の組み合わせ」です。製品のテストが苦手な人からすれば、テストを毎日させられるのはクソゲーかもしれませんし、プログラムを書くのが嫌いな人はプログラムを書かせられるのがクソゲーと感じると思いますが、得意な人もいます。たいていのゲームは一人でプレイするものですが、組織はチーム戦ですので、それぞれの得意な分野でフォローしあうことで、一人では大変なゴールをより簡単にできるようになります。

まとめ

- コミュニティづくりはゲームづくり

- ゲーム作成者とゲームプレイヤーは対等ではない

- うまく回ってないコミュニティはクソゲー

- 日々の仕事もゲーム

アート・オブ・コミュニティと「おもしろい」のゲームデザインの両方が、僕の考える最高の組織論の本です。読み手次第ですが、どちらも、仕事から趣味から、組織運営から、幅広く洞察を与えてくれる本だと思います。Sphinx-Users.jpは小さな核を持つグループですが、ドキュメントという、幅広いソフトウェアの分野に関わりあいを持つ可能性を持っています。今後もいろいろなゲームを作っていける余地があります。これらの本を眺めながら、このコミュニティでちょっとゲームを作ってみてはどうでしょうか？そろそろ総会があって、スタッフを募集しています。もちろん、ゼロから作るのも楽しいですよ。

13日目:「最近更新したページ一覧」を生成するsphinx拡張、recentpages

- 著者: @shiumachi

- 原文

アドベントカレンダーへの参加を大幅に遅刻しました。すいません。

この記事では、私が今年作成した「最近更新したページ一覧」を生成する sphinx拡張、sphinxcontrib-recentpages を紹介します。

sphinxcontrib-recentpages とは？

Sphinx プロジェクト内で作成した rst ファイルを更新された順にソートしてリスト表示するための Sphinx 拡張です。

この拡張を使えば、pukiwiki に標準で備わっている「最近更新されたページ」を表示することができます。

プロジェクトページはこちら: https://bitbucket.org/shiumachi/sphinxcontrib-recentpages

インストール方法

easy_install でインストールしてください。

$ easy_install sphinxcontrib-recentpages

その後、sphinx プロジェクトの conf.py に以下を追加してください。

extensions += ['sphinxcontrib.recentpages']

使い方

ディレクティブとサイドバー表示の2種類があります。

ディレクティブ表示

下記のように書けば、最近更新された直近 num 件を表示します。

.. recentpages::
:num: 3

サイドバー表示

conf.py に以下を追加してください。

# サイドバー表示を有効にします
recentpages_sidebar = True
# サイドバーの設定に recentpages.html を追加します。
html_sidebars = {'**': ['localtoc.html', 'relations.html',
'sourcelink.html', 'searchbox.html', 'recentpages.html']}
# サイドバーに表示するページの件数です。デフォルトは5件です。省略可
recentpages_sidebar_pages = 5

既知のバグ・制限事項・今後の予定

- 現在ファイルの更新日でしか更新時刻を取得していないので、git リポジトリで sphinx を管理している場合、git clone すると更新時刻が正しく表示されません。今後 git のコミットログを元に更新日を判断できるような機能を追加する予定です。

- mercurial にもそのうち対応する(かもしれません)

- 導入すると、make html 以外を実行できなくなります。make html 以外を実行するときだけ conf.py を編集するか、別にプロジェクトページを立ててください。いずれ修正します。

14日目: Sphinxで出力フォーマットごとに記述を変更する

- 著者: @r_rudi

- 原文

Sphinx アドベントカレンダー 2012 の14日目です。

Sphinxは一つのrstファイルからhtmlやepubなどいろいろな形式で出力することが出来ます。出力形式の差はSphinxが吸収してくれるため、普段は処理を意識する必要はなく単に make html と叩くだけなのがありがたいところです。

しかし、どうしても個々の出力先フォーマットに応じた処理を書きたくなる場合があります。特に顕著なのが画像の大きさで、htmlとlatexでは画像の大きさが倍違うことがあります。

そんなときに使えるのが only directiveです。

onlyの例

only directiveの例を記します。

.. only:: not latex

.. image:: figs/notation3.png
:scale: 40

.. only:: latex

.. image:: figs/notation3.png
:scale: 80

こう書くと、latexの場合はscale 80で、それ以外の場合はscale 40で画像が表示されることになります。

onlyの書き方

onlyに続く文字、上の例では not latex などですが、これは実は条件式です。ここには条件式とタグを記載できます。それぞれ使える内容は次の通りです。

- 条件式

- not

- and

- タグ

- makeで指定したbuilder名

- コマンドオプションで -t で指定

- conf.pyで指定

例えば、

.. only:: html and draft

の場合、html builderを使い、かつ、 -t draft と指定した場合にのみ出力されます。

詳しくは only directive を参照してください。

AutoImage拡張

onlyを使えば出力フォーマットごとに設定を変更できます。しかし、ほぼ同じ内容を二回書くのは手間ですよね。

ということで、Imageだけですが、builderごとにオプションを切り替えられる拡張があります。

AutoImage 拡張

これを使えば、以下のように簡単に記述できます。

.. autoimage:: notation3.png
:scale-html: 40
:scale-latex: 80

なお、 make html で実行するとこのオプションはキャッシュされてしまい、次に例えば make latex と実行してもhtmlの場合のオプションが使われてしまいます。

これを回避するためには sphinx-build に -E オプションをつけるとキャッシュを使わなくなります。

まとめ

出力先あるいは任意のタグで記述を変更できる only directive について紹介しました。また、AutoImage拡張を紹介しました。

Sphinxが出力フォーマットの面倒をすべて見てくれれば良いのですが、現実的には出力フォーマットに依存する処理は結構多いです。(特にLaTeX)そういうときにこのonly directiveを使うと適切な場合分けができるのではないかと思います。

参考

この記事は こちら を参考にしました。ていうか一部をそのまんま取り出しただけです。すいません。

15日目: pandoc で Redmine の Wiki を Sphinx に変換しよう

- 著者: @cointoss1973

- 原文

Sphinx Advent Calendar 2012 - connpass の 15日目のエントリとなります。本日は、pandocというドキュメント変換ツールの紹介です。 Sphinx を使う場合、reSTにてドキュメントを記述しますが、例えばプロジェクト管理にRedmineを導入している場合、Wikiに書きためた文章があるかと思います。RedmineのWikiは textile 記法なので、reSTにうまく変換する方法があったらいいと思いませんか？そんな textile を reST に変換してくれるツールとして使えそうな pandoc を紹介したいと思います。

pandoc とは

pandocは、ユニバーサルドキュメントコンバータです。 textileだけではなく、入力フォーマットとして、markdown, HTMLなどいろいろあり、出力も reST, markdown はもちろん、HTML, ePUB, PDFがあります。

pandoc のインストール

Pandoc - About pandoc から インストールできます。 Windows版も用意されており、簡単ですね

pandoc の起動

環境変数PATHが通っていますので、コマンドプロンプトから pandoc が実行できるハズです。

C:\Users\tkondou>pandoc -v
pandoc 1.9.4.2
Compiled with citeproc-hs 0.3.4, texmath 0.6.1.1, highlighting-kate 0.5.3.2.
Syntax highlighting is supported for the following languages:
Actionscript, Ada, Alert, Alert_indent, Apache, Asn1, Asp, Awk, Bash,
Bibtex, Boo, C, Changelog, Clojure, Cmake, Coffee, Coldfusion, Commonlisp,
Cpp, Cs, Css, D, Diff, Djangotemplate, Doxygen, Doxygenlua, Dtd, Eiffel,
Email, Erlang, Fortran, Fsharp, Gnuassembler, Go, Haskell, Haxe, Html, Ini,
Java, Javadoc, Javascript, Json, Jsp, Latex, Lex, LiterateHaskell, Lua,
Makefile, Mandoc, Matlab, Maxima, Metafont, Mips, Modula2, Modula3,
Monobasic, Nasm, Noweb, Objectivec, Objectivecpp, Ocaml, Octave, Pascal,
Perl, Php, Pike, Postscript, Prolog, Python, R, Relaxngcompact, Rhtml, Ruby,

Scala, Scheme, Sci, Sed, Sgml, Sql, SqlMysql, SqlPostgresql, Tcl, Texinfo,
Verilog, Vhdl, Xml, Xorg, Xslt, Xul, Yacc, Yaml
Copyright (C) 2006-2012 John MacFarlane
Web:  http://johnmacfarlane.net/pandoc
This is free software; see the source for copying conditions.  There is no
warranty, not even for merchantability or fitness for a particular purpose.

C:\Users\tkondou>

pandoc で、 Redmine の Wiki を Sphinx にする

redmineのwikiをsphinxに変換してみましょう。ひとまず対象は１ページです。

結果をおみせします。

変換前：https://my.redmine.jp/demo/projects/demo/wiki/Textile_test

変換後：http://cointoss1973.bitbucket.org/pandoc-sample/_build/html/index.html

Redmine.JP のデモサイトをお借りしましたm(__)m

code のところは、preタグの中身がそのまま変換されているので、シンタックスハイライトをしたい場合、 code-block などのdirective を使うように書き換える必要がありそうです。

今回行った手順

さすがに、pandocだけでページの更新まではできません。よって、下記のような手順をとりました。 [1]

- Redmine の Wiki から テキストファイルとしてダウンロード

- pandoc -f textile -t rst ~/Downloads/Textile_test.txt > index.rst

- Sphinx でビルド

pandoc の仕様 (1.9.4.2時点)

pandocの簡単な仕様をのせておきます。詳しくはドキュメントや pandoc -h をどうぞ。

入力フォーマット

オプション(今回使ったもの。一部)

さいごに

いかがでしたでしょうか。様々な形式のファイルをreSTに変換し、充実のSphinxライフを始めるのもいいと思います。明日は、 @shkumagai さんです。今年私がSphinxを始めた時の先生でした。素晴らしいエントリになること間違いないでしょう。よろしくお願いします。

参考

- Pandoc - About pandoc

- Pandoc - Pandoc User’s Guide

16日目: Sphinx Advent Calendar 16日目

- 著者: @shkumagai

- 原文

Sphinx Advent Calendar の 16 日目です。昨日は @cointoss1973 さんの pandoc で Redmine の Wiki を Sphinx に変換しよう でした。

今日のハナシ

5 日目を担当された @togakushi さんが題材にしている Sphinx HTML テーマを、自分も取り上げてみようと思います。

HTML テーマ事始め

今年 9 月の SphinxCon JP 2012 で Sphinx HTML テーマを題材に発表をしたのですが、その発表の追補という位置づけです。

自作 HTML テーマを zip で配布する

SphinxCon JP 2012 の発表では自作のテーマのディレクトリ構成を提示して、そのディレクトリを直接指定してテーマを読み込ませる、という手法を紹介したわけですが、この手法には「複数人数で同じテーマを使いたい場合に、面倒くさい」という短所があります。

テーマを一つのディレクトリとして構成しているので、そのディレクトリをまるごと共用しないといけないわけです。ちょっとこれはイケてないですよね。

はて、どうしたものか... というところですが、 Sphinx の公式ドキュメントには以下のような記述があります :

If the theme does not come with Sphinx, it can be in two forms: either a directory (containing theme.conf and other needed files), or a zip file with the same contents.

テーマが Sphinx に付属していない場合、次の２つの方法で指定できます: ディレクトリ（ theme.conf とその他の必要なファイルを含む）か、同じ内容の zip ファイルのいずれか、です。

ということで、ここでは HTML テーマ を zip ファイルにまとめる方法を紹介したいと思います。

ちょっと復習

さて、自作の HTML テーマということですが、どうやって作ればいいのか分からない方向けの説明も兼ねて、ちょっと復習してみましょう。実際にここに示すように作ってみて、動作確認をすると理解が進むと思うので環境が用意できる方は、手を動かしながら読んでいくと良いと思います。もちろん、既にご存知の方はこの節は読み飛ばして頂いて結構です。

まず、Sphinx の HTML テーマは以下のような構成になっています。

<theme_top>
+ theme.conf
+ template ファイル (例えば layout.html など。必要な場合のみ)
+ static/
+ CSS ファイル
+ 画像ファイル (必要な場合のみ)

このうち、絶対に必要なものは一番上にある theme.conf だけです。その下にある layout.html や CSS ファイルは変更を加える必要がないときには、テーマに含める必要はありません。

ここで仮に mytheme というテーマを作成すると仮定して、構成を見てみることにします。適当なワーキングディレクトリに mytheme というディレクトリを作成し、その下に theme.conf を作成してみましょう :

$ mkdir mytheme
$ cd mytheme
$ vim theme.conf

theme.conf の中身は次のようにします。

[theme]
inherit = sphinxdoc
stylesheet = mytheme.conf
pygments_style = friendly

次に static ディレクトリを作成して、その下に mytheme.css を作成します :

$ mkdir static
$ cd static
$ vim mytheme.css

mytheme.css の中身は次のようにします。変更したスタイルが適用されていることが確認しやすいように、背景色だけ変更しておきましょう :

@import url("sphinxdoc.css");

body {
background-color: #dbd0e6;
}

ここまでで mytheme ディレクトリの下は次のような構成になっているはずです :

mytheme
+ theme.conf
+ static
+ mytheme.css

そうしたら mytheme ディレクトリの直下に戻って、次の手順で zip ファイルを作成してみましょう :

$ zip -r mytheme.zip *
$ ls -F
mytheme.zip static/     theme.conf

zip ファイルができあがりましたね。そうしたら作成したテーマを適用したい Sphinx のドキュメントプロジェクトディレクトリの中で conf.py と同じディレクトリに mytheme.zip を置き、 conf.py を次のように編集します :

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'mytheme'

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ["."]

ポイントとして html_theme_path の値は conf.py からの相対パスを指定します。コメント部分にも書いてありますが、注意しましょう。

あとはいつものとおり、 make html を叩くだけです。

どうでしょう、背景色が薄紫色に変わった sphinxdoc テーマのページが表示されたでしょうか？上手く表示できたら成功です。逆に make html を実行した後にエラーメッセージが出てしまっている場合は、テーマがうまく読み込めていない可能性があります。この記事のコードスニペット部分と手元のコードをよく見比べてみてください（そしてもしタイポを発見した場合にはコメントをして頂けると助かります）。

おわりに

Sphinx HTML テーマは、ご覧頂いたような手順で簡単に継承・上書きして、配布することができます。しかも HTML テーマのカスタマイズに関して言えば、大掛かりな構造の変更でない限りは Python の知識が無くてもなんとかなります((もちろん、Sphinx が吐く HTML は御世辞にもキレイとは言えないのと、継承元のテーマで適用しているスタイルとの兼ね合いがあるので意図した通りにスタイルを変更するのはなかなか難しいかも知れませんが、そこは Try and Error で慣れていく必要がある部分だと思っています。))。

もし自作のテーマを手元に抱えたままにしているのであれば、この方法を使って他の人にも配ってみてください。

明日は @kashew_nuts さんです。よろしくお願いします。

参考

- HTML theming support

- HTML テーマ事始め -

17日目: Tinkererでブログを書こう

- 著者: @kashew_nuts

- 原文

Sphinx Advent Calendar の17日目を書きます。 @kashew_nuts です。

Tinkererとは

Tinkerer とはSphinxを使ったブログ作成ツールです。 Sphinx Advent Calendar 2012 (全部俺) の @usaturn さんや、 Sphinx Advent Calendar 2012 主催の @r_rudi さんもTinkererを使用しています。今回はそのTinkererについて導入から実際に公開するまでの一連の流れを紹介してみたいと思います。

(注意)2012/12/17現在、最新バージョンは1.0.1 ですが、既に0.4.1b以下を使用している方はUpdateは控えたほうが無難かと思います。formatの形式にバグがあるらしく、インストールしてもビルドできないことがあります。

事前準備

以下が用意されていることを前提としています。

- Python2.x (当方 Python2.7を使用しています)

- pip

- mercurial

- virtualenv, virtualenvwapper(お好みで)

bitbucketの準備

- bitbucketに以下の名前でリポジトリ作成

<username>.bitbucket.org (private レポジトリ)

(注意) <username>には_(アンダーバー)などの記号を含まないほうが無難です。記号が含まれていた場合、Twitterのような外部サービスと連携したい時に問題が発生することがあります。私のアカウント名は通常 kashew_nuts を使用していますが、そのままのアカウントで作成すると、TweetボタンでブログのURLが作成されず困りました。

初期設定

以下のようにするとブログを書くのに必要なファイル類ができあがります。

$ pip install tinkerer==0.4.1b (Tinkererのインストール)
$ mkdir myblog
$ cd myblog
$ tinkerer -s (Tinkererの初期セットアップ)

次にブログのタイトルやあなたの名前を登録しましょう。お好きなエディタで conf.py を編集します。私は普段 Vim を使用しているので Vim で書きます。シンタックスハイライトが特別な設定なしで使えるため非常に便利です。

$ vim conf.py

例として以下に私が設定している conf.py を上げたいと思います。 ''でくくられている箇所をお好きな内容に変えて設定して下さい。

# Change this to the name of your blog
project = u'kashew_nuts-blog'

# Change this to the tagline of your blog
tagline = u'つらつらと'

# Change this to your name
author = u'Kashun Yoshida'

# Change this to your copyright string
copyright = u'2012, ' + author

# Change this to your blog root URL (required for RSS feed)
website = 'http://kashewnuts.bitbucket.org/blog/html/'

日本語環境用にパッチを当てる

Version0.4.1bのTinkererをインストールしましたが、日本語環境で使用するとUnicode Errorでビルドに失敗するようです。以下のURLを参照し、パッチを当てて下さい。 https://bitbucket.org/vladris/tinkerer/issue/47/a-unicode-error-occurred-when-lc_all-is

手元の Mac OSX + virtualenv 環境では、 lib/python2.7/site-packages/tinkerer/cmdline.py にありました。パッチの内容通り import locale と locale.setlocal(... の2行を削除するとビルドできるようになります。

これで、Tinkererでブログを書く初期設定は終了です。

ブログを書こう

$ tinkerer -p "first post" (記事の下書き作成)
$ vim 2012/12/17/first_post.rst (記事の作成)
$ tinkerer -b (記事のHTMLを作成)

これで、blog/html/以下に記事が作成されます。どんな記事が作成されたのか、以下のコマンドを打って確認してみましょう。

$ pyhton -m SimpleHTTPServer

ネットワーク受信接続の許可を求められますので、 許可 を選択して下さい。ブラウザのロケーションバーに http://127.0.0.1:8000 とタイプすると、あなたが作成した記事を確認することができます。

SimpleHTTPSererのデフォルトのポート番号は8000ですが、以下のように記述するとポート番号を指定できます。この例ではポート番号を8080に設定しています。

$ pyhton -m SimpleHTTPServer 8080

ブログを公開しよう

いくつかあるようですが、ここは私が実際に使用している方法を紹介したいと思います。初めに準備した bitbucket リポジトリに以下の2つを上げてしまいましょう。

- index.html

- blog 以下全て

Mercurial を使用した方法を記述します。

$ hg init
$ vim .hg/hgrc

[paths]
default=ssh://hg@bitbucket.org/<username>/<username>.bitbucket.org

$ hg add index.html
$ hg add blog/.
$ hg commit -m "first post"
$ hg push

公開されるまでに数分程度待つかもしれません。数分後 https://<username>.bitbucket.org にアクセスすると、ブログページが表示できるようになります。

早くVersionからβが外れたTinkererを使用してみたいですね。明日(18日)の担当は @feiz さんです。よろしくお願い致します。

参考

- Documentation — Tinkerer

18日目: "ドキュメントを部分的に公開/非公開にしてビルドする"の実用例

- 著者: @feiz

- 原文

Sphinx Advent Calendar 2012: 18日目

おひさしぶりのfeizです。久しぶりついでにはてブロに移行してみました。

先日、こんなcookbookを投稿しました。

ドキュメントを部分的に公開/非公開にしてビルドする :: ドキュメンテーショ ンツール スフィンクス Sphinx-users.jp

仕事でお客さん向けのドキュメントを書いてると結構需要のある話なんじゃないかなーと思ってます。ただ、cookbookには実際の利用例みたいなものをあまり入れられなかったので、この機会に実用例や設計手順をまとめてみようと思います。

前提とするシチュエーション

以下のようなシチュエーションを想定します。

- とあるB2BサービスのAPIサーバーを書いている

- 自社(開発)→サービス元(サービス運用)→エンドユーザー(複数社)

- サービス元とエンドユーザーと自社内の3ロールにそれぞれドキュメントを提供しないといけない

ドキュメント間の関係の設計

内容を考え始める前に、各ドキュメントがどういう関係になるかを設計しておきます。

大抵の場合、自社向けドキュメントには全部載せの内容が出るのが望ましく、自社から離れるに従って内部仕様が削られていくような構造になってほしいはずです。

つまり

自社向けドキュメント⊃サービス元向けドキュメント⊃エンドユーザー向けキュメント

のような構造です。

これにしたがってビルド時のタグ付けを決めます。

更に、エンドユーザーには複数社あるので、"user"に加えて各社それぞれにタグを割り当てておきます。

ドキュメントの構造設計

まずは全部込みの構造を考えてみます。

/spec/    => サービス概要/用語説明など
/admin/    => 管理ツールの使い方
/api/   => API毎の詳細仕様
index.rst

こんなかんじにしましょう。

ここから、更に各出力設定によってどういう風に出し/消ししたいかを考えます。

1. /api/

user向けには内部APIは出してはいけないので、userタグがついた場合にはそれらが消えるべきです。

/api/developer/ディレクトリを掘り、内部APIに関するドキュメントは全てそこに纏めることにします。

後は、conf.pyでdeveloperディレクトリのexclude設定を書けばOKです ( 参照)

if 'user' in tags:
exclude_patterns += ['/api/developer/*']

ここで、"/api/developer/*"の代わりに"*/developer/*"という指定にしておくと、どんな場所でもエンドユーザーに見せたくないものは全部developerディレクトリを掘って入れるだけで消し去れます。以降はこの設定をしたものとして進めます。

2. /service/

サービス概要は、文書丸ごとの出し分けよりはセンテンス単位での出し分けが多そうです。

センテンス毎の出し分けは、onlyディレクティブで実現できます。(参照) ただし、参照記事にもあるようにセクションの出し分けはできません。装飾をつけた文字で代用するなどの工夫が必要です。

/service/grossary.rst

:`みんな死ぬしか`: ないじゃない
.. only:: not user

:`ユーザーのみんなには`: ナイショだよ

3. /admin/

serviceとほぼ同じですが、各ユーザー向けの情報（管理画面のログインIDなど）を載せる必要があるかもしれません。

このような場合に各社毎のタグ定義が役に立ちます。

admin.rst

管理画面ログインIDについて
=============================

.. only:: Asha or not user

:ログインID: asha_1234

.. only:: Bsha or not user

:ログインID: bsha_1234

このような記述にしておくと、非ユーザー向けドキュメントには全ログインID が表示され、ユーザー向けドキュメントには対象のユーザー向けのものしか出ないという挙動になります。

書く

出し分けの構造設計までできれば、あとは書くだけです。

ひたすら書いて下さい。

まとめと注意点

- 設計重点

この手法をうまく適用するには、事前の設計がとても重要です。

適当に書いていると、excludeしたドキュメントにリンクが必要になったり、セクションを消す必要が出てきたりしてスムーズに進められません。

- 動作確認する

表示非表示のロジックを仕込み始めると、当然バグを仕込む可能性が出てきます。

adminの項で例に出したログインIDの出し分けなどは、間違って出てしまうとえらいことになります。

動作チェック/出力内容チェックのワークフローは用意しておくべきでしょう。

- 頒布物にソースを含めない

「絶対に見えてはいけない」情報を出し分ける場合には、必ずconf.pyでhtml_copy_sourceをFalseに設定しておくようにしましょう。ここをTrueにしたままだと、ソースのrstファイルが配布物に含まれてしまうため、onlyで隠しているつもりの情報が見えてしまいます。

おわり

こんなかんじに、プログラマブルなドキュメントを書けるのはSphinxの素晴らしい所の一つだと思いますが、バッドノウハウめいたものが多数含まれているのも事実です。搦め手に頼りすぎず、用法用量を守って正しくお使いください。

明日は世界の小宮リターンズです。

1回目の記事 はマジメな内容だったので、今度は抱腹絶倒間違い無しの大ネタを仕込んできてくれることでしょう。

19日目: Sphinx 文書に markdown フォーマットを利用する

- 著者: @tk0miya

- 原文

この記事は Sphinx 文書に markdown フォーマットを利用する の 19日目です。

markdown と Sphinx (reST)

Sphinx では文書を書く際の記述フォーマットに reStructured Text を利用していますが、世を広く見回すと、github 然り、bitbucket 然り、様々な場所で markdown フォーマットが利用されています。 markdown フォーマットは reST と比べると表現力が低い上、表現を拡張することができないという点が指摘されています。表現を拡張することができないため、いくつかの方言が存在するという問題もあります。

ですが、reST と比べてシンプルで、なおかつポピュラーに利用されているフォーマットであるため、新しく Sphinx に触り始める人の取っ掛かりとしては、markdown はうってつけのフォーマットと言えます。

sphinxcontrib_markdown

それでは、Sphinx を markdown を利用するための拡張 sphinxcontrib_markdown を利用します。今しがた作ったばかりの新しいプログラムなので、gist からソースコードを保存してください。

$ wget https://gist.github.com/raw/4336929/25dfcaad2b2d63a973617757062cec3ab9c31c35/sphinxcontrib_markdown.py

そして、conf.py に以下の記述を追加します。

sys.path += ["."]
extensions += ["markdown"]

markdown_title = 'hello world'
source_suffix = '.md'

そして、markdown で書かれた文章を Sphinx プロジェクトディレクトリに配置します。なお、この時に index.md というファイル名は 利用しないでください 。

あとは、いつもどおり make を実行します。

$ make html

そうすると、markdown を Sphinx で変換した HTML を得ることができます。もちろん PDF や ePub にも変換することが可能です。

sphinxcontrib_markdown の仕組み

sphinxcontrib_markdown は Sphinx が markdown ファイルを読み込む際に、 pandoc を利用して自動的に reST フォーマットへ変換して Sphinx に取り込んでいます。

また、markdown には toctree に相当するものがなく、各ページをつなぐ目次を生成することができないため、 sphinxcontrib_markdown モジュールでは、ソースとなる markdown ファイルすべてに対する toctree を自動的に生成します。そのため、make html を実行すると自動的に index.md が生成されます。

まとめ

今日は Sphinx から markdown フォーマットを利用するための sphinxcontrib_markdown モジュールを作成しました。内部では様々なイベントハンドラを利用したり、Sphinx に実行時パッチを当てて動きを変えたりと、割と無茶なことをしていますが、 Pro GIT を変換してみたところ特にエラーなく Sphinx ドキュメントとして変換することができました。(一部 pandoc 由来のワーニングが出ます)

僕自身は普段まったく markdown を書かないため、「作ってみた」に近い状態ですので、どなたか実際に使ったりいじったりして、突っ込んでもらえると助かります。

では、明日は @r_rudi さんの番です。楽しみにしてます :-)

20日目: Sphinxで図に番号をつける

- 著者: @r_rudi

- 原文

Sphinxアドベントカレンダー2012 の20 日目です。

Sphinxで論文などを書くときに "図1 に示す" などのように、図番号への参照を書きたくなりますよね。

しかし、残念ながらsphinxは標準では番号をつけて図を参照できません。

そこで numfig拡張 の出番です。

インストール

# 好きなところに移り
% cd /path/to/somewhere
# リポジトリをclone
% hg clone https://bitbucket.org/arjones6/sphinx-numfig

あとは conf.py に

# リポジトリをパスに追加
sys.path.insert(0, os.path.abspath('/path/to/sphinx-numfig'))
# extensionsに追加
extensions = ['numfig']

これで準備はオーケーです

書いてみる

numというroleが追加されます。例えばこんな感じで使います。

:num:`図 #rrudi-fig` の奴は :ref:`rrudi-fig`

.. _rrudi-fig:

.. figure:: r_rudi-icon.png
:width: 100px

だめrudi

もう少しちゃんとしたサンプルを書きましたので、ご覧ください。

http://tdoc.info/tmp/numfig/

使えるrole

num

図番号への参照。 #refターゲット と書く。

ref

ラベルへの参照

page

ページへの参照。これはLaTeX出力の場合だけ使われる。

conf.pyで出来る設定

number_figures

TrueかFalse。Trueの場合図の番号も含めて出力する

figure_caption_prefix

キャプションの頭につく文言。デフォルトは"Figure"。日本語にするときは u"図" などのようにuをつけること

まとめ

これで図もばしばし使えますね。

さて、明日は r_rudi さんです。よろしくお願いします。

21日目: SphinxでCSSのclassを変更する

- 著者: @r_rudi

- 原文

r_rudiさんから引き継ぎました、 Sphinx アドベントカレンダー 2012 21日目です。

Sphinx MLから拾ってきた小ネタです。

Figureをセンタリングしたい

figureやimageを使って画像を貼り付けたはいいけど、センタリングしたい！と言うときがあるかと思います。

そういうときは、以下のように、 :figclass: オプションをつけてみましょう。こうすると、CSSのクラスに指定したクラスが付け加わります。

.. figure:: hoge.png
:figclass: align-center

この例では align-center というクラスが加わり、センタリングされます。

デフォルトのテーマでは

- align-center

- align-right

- align-left

が設定されていますので、お好みに応じて設定すると良いと思います。

あるいは、自分でCSSを定義しておき、好きなクラスを振ることもできます。また、空白区切りで複数書くこともできます。

classオプション

さて、このfigclass、実は他のディレクティブにも使える場合があります。

.. csv-table:: Frozen Delights!
:class: something-special-class

"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out"
"Gannet Ripple", 1.99, "On a stick!"

こんな感じで例えばcsv-tableにも設定出来ます。

詳しくは ディレクティブの紹介 を参照してください。

classディレクティブ

上のはディレクティブに対するオプションでした。でも、たまには「このパラグラフにクラスを適用したい！」ということもあるでしょう。

そういう場合には、 rst-class ディレクティブを使います。

.. rst-class:: hoge

ほげですよ

こう書くと、「ほげですよ」の部分がhogeクラスとなります。

なお、通常のdocutilsでは class ディレクティブを使うのですが、 Sphinxではデフォルトドメインに class ディレクティブが存在するため、このディレクティブはそのままでは使用することができません。そのため、 rst-class という名前で再定義されています。

この辺は reStructuredText入門 を参照してください。

まとめ

今回は表示のときにクラスを制御するというちょっとしたtipsでした。

明日は @Harrison さんです。よろしくお願いします。

22日目: Sphinx アドベントカレンダー22日目

- 著者: @Harrison

- 原文

こんにちは、クレイジーなHarrisonです(｀･ω･´)ゞ　巷ではブロックダイアグを使うようなアホだと言われていますが、いかがおすごしでしょうか。寒くなりました。何やらアドベントカレンダーというものが続行中のようであり、これに滑り込まないわけには行かないと思った次第なので飛び込みます⊂（ﾟДﾟ⊂⌒｀つｽﾞｻﾞｰ

なお、今回技術的な話はしません。主にどう使っているかという話をします。知識がない私はまさかりレーダーに狙われる生活をしており、技術的な発言をしようとすると四方八方からまさかりが飛んでくるおそれがあるのです。今年の◯◯ JPプロレス場でも、周囲に飛び交っているまさかりを見て震え上がりました。その恐怖の中、これを書きます。

Sphinxをなぜ使うの？

ファイルを分割して書けるから。何よりもこれです。HTML出力とか翻訳するとき役立つというのもありますが、やはりひとつのファイルでなくてよいのは助かります。メモだとか、ノートだとか、そういったのがブワーっと文字で溢れてると、結構うんざりします。キチンとレポートやら論文を書こうとしたときはこれが困るんです。整理がしにくい。論理的に書くとは、整理して構造を意識して書くということだと思います。

構造的に書くとは

ピラミッドを意識して書くということです。マインドマップを思い浮かべるといいかもしれません。雰囲気的には近いです。「論理トレーニング」で述べていることにせよ、ベースにあるのはきちんと分解して、構造を把握するということだと思います。index.rstというひとつのファイルからどう分割してそれぞれのファイルをつなげてくかについてはPyプロを参照するといいと思います。

構造を意識するとき、どの文章でも着目すべき点はこの３つです。それは、主張、根拠、その２つをつなぐ導出。メモやらなんやらで文字が溢れかえっていると、これらがとてもつかみにくくなります。

ちょっと詳細に述べてみます。こんな箇条書きのメモがあったとしましょう。

* 壁ドン　こみやさんに
* はり　クレイジー
* ぶろっくでぃあぐ

いや、どんなメモですか。これを整理すると、こうなります。

ここから、文章を書きなおすと次のとおりです。「ハリソンはクレイジーである。理由は2つある。第一に、blockdiagを使っているからであり、第二にこみやさんに壁ドンされたいからである( 〃▽〃)」と、こんな感じに整理できます。意味はわかりませんが、整然とした気がします。

そんなわけで、一定程度を超える文量のものを、理路整然と書くことを意識するならSphinx使ってみるのもありですよというお話でした。

そういえば、去年かな？　"ドキュメントを書くツール"と聞いて、「こあい！！」「ドキュメントって何??((((；ﾟДﾟ))))」と身構えてました。でも、ハッカソンにこっそりお邪魔するようになり、次第に質問を投げまくったりして（すませんでした）、その不安は消えました。（特にこみやさんにはありとあらゆる場所でかなり質問させていただきましたm(_ _;)m）

みなさん、文章書いた経験はありますよね？何枚も書いてるうちに、消しゴムはこれがいいとか、こっちのシャーペンよりこのシャーペン使いたいとか思うようになって。そんなのと同じで、パソコンの鉛筆にこだわるぐらいのつもりで気楽に構えるといいんじゃない？あ、こんなうかつなこと言うとマサカリがうわなにをすくぁwせdrftgyふじこlp

参考文献とか

- The Pyramid Principle by Barbara Minto

← ピラミッドとは主にここで紹介されている概念です。訳書もありますが、原書の英文はとてもシンプルなので、こっちを読む方がいい気がします。

- 新版 論理トレーニング 、論理トレーニング101題 by 野矢 茂樹

← 主にこの2冊は、特に後者ででてくる問題でも、分解して整理するということにつきるのではないかという印象です。具体的な仕方などはこの辺の本で。

- Pythonプロフェッショナルプログラミング by ビープラウド

← Sphinxに関することは、ドキュメントそのもののことから導入などまで、とりあえずまず最初に参考にするとよさげ。内容が１番まとまってるので。

- https://twitter.com/usaturn/status/280227267832074240 ((゜ω゜))

僕が使い始めるまで参考にしたものなど

- Sphinx & blockdiag Advent Calendar(全部俺) : ATND http://atnd.org/events/22450

←昨年のこみやさんのもの。導入〜翻訳についてこの辺を参考にしました。

- "Sphinxをはじめよう :: ドキュメンテーションツール スフィンクス Sphinx-users.jp" http://sphinx-users.jp/gettingstarted/index.html

←導入で1番参考にした場所です。

- kashew_nuts-tech: reST→PDF出力の環境を整備した。 http://kashewnuts-tech.blogspot.com/2012/06/restpdf.html

←困ったとき助かりました(´ω｀)

- "発表資料 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp" http://sphinx-users.jp/doc.html

←Sphinxとは何？という人がまず見るといいと思うもの。「ドキュメントを作りたくなってしまう魔法のツールSphinx」のスライドは情報がつまっていて、とても役立ちました。

- "Overview — Sphinx 1.1.3 documentation" http://sphinx-doc.org/

←初心者の僕がつまづいたのは、導入と日本語周りです。導入については、ここに書いてあるように"easy_install -U Sphinx"と入れて解決しました。「-U」のおかげでうまくいったみたいです。うさたーんさんに教えていただきました。

キャッチボール

@r_rudi ヽ(・ω・ヽ）はいよっ

( ﾉ・・)ﾉﾊﾟｽｯ!　@tboffice

23日目: Sphinxで薄い本を書いてみた

- 著者: @tboffice

- 原文

Sphinx Advent Calendar 2012 - connpass の23 日目です。 昨日は Harrison さんの Sphinx アドベントカレンダー22日目 でした。壁ドンって重ねるとたのしいですよね。壁壁ドンドン [1] 。関係が前に進みそうな感じですね [2] 。ということでAdvent Calender初参加でございます [3] [4] 。

はじめに

Sphinx界隈の皆様、はじめまして。柱脚の多さで定評のある @tboffice と申します。よろしくお願いします [5] 。 Sphinxで薄い本を作った話をします。薄い本については最後の方で触れます。

そもそも

実は、このエントリのタイトルにもなっている「薄い本」は、今年の夏頃にも作りました。そのときは複数人で素のtex原稿を書いて持ち寄って、dvipdfmxコマンドをたたいてビルドしていました。

そのとき一緒に執筆していた id:j5ik2o (@j5ik2o)さんからこんなのあるよ、という紹介で sphinxを知りました。rst形式で文章を書けばいろんなフォーマットで出力できるよ、という話をきいて調べてみるとepubも出せるぞ！これは電子書籍化が簡単にできるぜゲヘヘ [6] ということで、使ってみることにしたのでした。

執筆の流れ

1. 各自の記事のrstを書く

2. $ make latexpdfjaしてpdfを生成

3. pdfを印刷屋さんに入稿

4. おしまい [7]

この流れの間に、いろいろなことが含まれているので、ひとつひとつ解きほぐしていきます。

環境構築

TeX Live 2012 をインストールしている環境があったので、そこにsphinx 1.1.3 もインストールして利用しました [8] 。その後、dvipdfmxを使うために下記のパッチを適用しました。

LaTeX経由でのPDF作成 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

いざrstを書く

githubに慣れてしまった若者のrst離れが叫ばれている中、我々はrstという茨の道（ｒｙ [9] ）

複数人で原稿を書いていたので、各自rstを覚えるというところからスタートしました。自分の感覚だと、rstを覚えるのはMarkdownやはてな記法より障壁高めという印象でした。構造を理解するまで1-2日程度かかりました [10] 。

自分が理解したところで、まだ覚えてない人には、基本的なのrst記法と、それに対応するpdfを出力して対比して見せました。

余談ですが、締め切りが近くなった頃、各自のセクションの記号は統一されていないことが発覚。あとで大変なことに…。

セオリーに倣って統一しましょう：reStructuredText入門 — Sphinx v1.0 (hg) documentation

みんなでrstを書く

1つのファイルをみんなでよってたかって編集すると衝突するので、include的な仕組みを使いました。 index.rstにこんな感じで記述しました。

.. toctree::
:maxdepth: 4
:numbered:

first.rst
hoge/fuga.rst
second.rst
foo/bar.rst

pdfのフォーマットを決めていく

入稿するpdfの仕様は、「モノクロ・B5サイズ・フォント埋め込み済み」です。

jsarticleを使いたい

デフォルトでpdfをビルドしようとすると、sphinx.styを使ったa4paper的な PDFが出来ます。これを入稿する仕様に合わせていきま す。早速、conf.pyの編集です。デフォルトのpdfの見栄えがアレゲだったので、jsarticleを使いました。すると、\chapterが表示 されないという問題が発生。それもそのはず、 jsarticleはchapter表示できないのでした。jsbookにすれば\chapterを解釈できるのですが、ページ数をふんだんに使ってしまうのと、前回jsarticleで本を作ったのでjsarticleをどうしても使いたい！という状態になりました。結局 howto にして jsarticle を使う設定にもっていってそこから小手先の技術を使います。

\partが出力できなかったので、rstファイルに 「.. raw:: latex」を書いてそこに \part を書き込むというよろしくない感じになりました。仕方ないのです。偉い人にはそれがわからんのです [11] 。

ページ数がローマ字に

なってしまったので、conf.pyのpreambleで「\pagenumbering{arabic}」を設定して解決。

コードブロックに枠線を付けたい

という要望が執筆者から挙がりました。調べてみたのですが、結局生成した texファイルをsedして置換するということで対応 [12] 。

$ sed -i -e 's/commandchars/frame=single,commandchars/' $TEXFILE

このあたりの解決は、入稿まで時間のない中、 id:mtgto /@mtgto に何とか解決してもらいました。多謝。

コードブロックのカラーリングをオフにする

デフォルトでコードブロックにカラー設定がされています。入稿するPDFはモノクロで作ろうとしていたため、dvipdfmxでグレースケールにするオプション (-c)を使ったところ、コードブロックの部分がすべて四角い黒ベタになってしまいました [13] 。

コードブロックのカラー部分をすべてモノクロに出来ないかと、生成された texファイルを見てみたところ、カラー設定が書かれている部分がありました。しかし、定義行数が多すぎたためなんとかせず、印刷屋さんでグレースケール化してもらいました [14] 。

blockdiag

試しに使ってみると、pngで画像が生成されて、platex が png を食えなくて止まるという現象に遭遇。 extractbb で xbb ファイルをどうにかこうにかするというところまで辿り着いたのですが、そこから先がなんとか出来ずにblockdiagを使うのを諦めました [15] 。結果的にはblockdiagを使わなくてもなんとかなりました...

印刷関連

sphinxから離れますが、ついでなので印刷関連のお約束に触れておきます。

PDFフォント埋め込み問題

フォントを埋め込むか、アウトライン化しないと、別の環境でpdfを開くとフォントが再現できず、化けることがあります [16] 。今回は下記サイトの記述通りにやったらうまくいきました [17] 。

日本語フォントのセットアップ

今回こんなコマンドを打ちました [18] 。

# updmap-setup-kanji ipaex

ページ数

ページ数は「4ページ単位」を意識しないと面倒なことになるので、本文のページ数は注意しましょう [19] 。

できなかったこと

字下げができない

できあがったPDFファイルで、文章の1行目の字下げができませんでした。そんな文句をかいたエントリにコメントを書いてくださった方がおりまして、preambleに「\setlength\parindent{1zw}」と書いたところ、意図したとおりになりました。この場をお借りしてありがとうございます。入稿には間に合いませんでしたが、次回への糧としていきます。

まとめ

- sphinx.styを使わずに素のTeXファイルを出してくれないもんかなあ

- rstで文章中に柱脚を書くとき、TeXでいうところの\footnote{}的な書き方できないっすかねー。はてな記法だと柱脚は二重括弧なのでそんな感じがあると嬉しい [20]

え？薄い本はどうしたって？

そんなsphinxでビルドした「薄い本」のタイトルは、「ななかInside Press vol.2」です。冬コミ3日目の12/31(月)の大晦日に頒布しますのでみんな来てね [21] ！スペースナンバーは東Y14b だよ [22] ！

特集はGitとなっております。私は特集記事の中で、「Git + Jenkins + Sphinxでドキュメント生成」の記事を書きました [23] 。なお、本の奥付にQRコードがありましてそれを読み取ると＜censored＞自分でビルドできます [24] 。

詳細は http://nanaka-inside.net でチェックしてください。

おわりに

sphinxのことだったら何でも書いて良い気がするという雰囲気を感じ取ったので今回参加させていただきました。ひどいステマで申し訳ありませんでした。このエントリが何かのお役に立てれば幸いです。バッドノウハウに対するナウでヤングなグッドノウハウを教えていただけるとありがたいです。

明日は、@tcshさんです。

追記(2013/01/05)

あけましておめでとうございます。当日お越しいただいた皆様、ありがとうございました。まだ手元に若干の在庫がございますので、「とらのあな」に委託します。新刊・既刊とも委託します。もしよろしければどうぞ。

24日目: Start Sphinx Documentation

- 著者: @tcsh

- 原文

Sphinx Advent Calendar 2012 24日目担当の 波田野 ( @tcsh ) です。

今回は、Sphinxを使ってドキュメントを作るときに、自分がやっている手順を書いてみます。

ノート

Sphinx環境の構築については今回は書きません。

自分は、下記を使って書いています。 (2012-12-24 時点)

- Sphinx 1.1.3

- Mercurial 2.4

- vim 7.3.661

おおまかな流れとしては、

1. リポジトリを作成する

2. Sphinxドキュメントのセットアップをする。

3. コンテンツのlocal公開

4. .hgignore の作成

5. Sphinxドキュメントの基本パーツ作成

6. 最初のコミット

7. ドキュメント本体を書き出す

という感じです。

警告

ツッコミやアイデアがあれば、Sphinx-Users-jp ML や #sphinxjp で是非よろしくお願いします!

Contents

- 24日目: Start Sphinx Documentation

- 1. リポジトリの作成

- 2. Sphinxドキュメントのセットアップ

- sphinx-quickstart の実行

- Makefile の編集

- conf.py の編集

- リポジトリへの追加

- 3. コンテンツのlocal公開

- コンテンツの初ビルド

- コンテンツのlocalhost公開

- 4. .hgignore の作成

- 5. 基本パーツの作成

- 5.1. タイトルの編集

- 5.2. リファレンス名の追加

- 5.3. トップへのリンクの追加

- 5.4. modindexの削除

- 5.5. 置換テーブルの作成

- 5.6. 用語集の作成

- 5.7. コンテンツをビルドしてみる

- 5.8. リポジトリへの登録

- 6. 最初のコミット

- 7. ドキュメントの作成

- 7.1. プロダクトドキュメントの作成

- 7.2. 運用ドキュメントの作成

- 8. おわりに

1. リポジトリの作成

まず、ドキュメント用のディレクトリを作成します。

command:

% setenv TARGET_DOC $HOME/work/hg/sample-sphinx
% mkdir ${TARGET_DOC}
% cd ${TARGET_DOC}

Mercurial のリポジトリを作成します。

command:

% hg init
% ls -a

result:

.     ..      .hg

2. Sphinxドキュメントのセットアップ

sphinx-quickstart の実行

sphinx-quickstartを実行します。

command:

% sphinx-quickstart

以下の3つ以外はデフォルト値を使っているので、エンター連打してます:-)

> Project name: Sphinx Sample Product document
> Author name(s): HATANO Hirokazu
> Project version: 1.0

ノート

- いつか使ってみたいもの

- epub builder

- intersphinx

- todo

- coverage

- ifconfig

- make.bat は、稀にWindowsでビルドすることがあるので、一応作っています。

result:

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Makefile の編集

Sphinxのワーニングログをファイル(./_warn.log)に出力する設定を Makefile に記述します。

Makefile (diff):

- SPHINXOPTS    =
+ SPHINXOPTS    = -w _warn.log

conf.py の編集

オレオレテーマを _themes 下にシンボリックリンクで置いているので、それを使う設定をします。

conf.py (diff):

- html_theme = 'default'
+ #html_theme = 'default'
+ html_theme = 'tcsh'

- #html_theme_path = []
+ html_theme_path = ['_themes']

sphinx-quickstartが作ったタイトルでは長過ぎるので、書き換えます。

conf.py (diff):

- #html_title = None
+ html_title = project

smartpantsは手順書系の記述でわるさ(クォート系が自動置換される)するので False にします。

conf.py (diff):

- #html_use_smartypants = True
+ html_use_smartypants = False

ノート

extensions は、ここでは省略します。共通でインクルードする方法をさがし中。

リポジトリへの追加

この時点で、管理系ファイルをリポジトリに追加しておきます。

command:

% hg add Makefile conf.py index.rst make.bat

result:

Makefile を追加登録中
conf.py を追加登録中
index.rst を追加登録中
make.bat を追加登録中

3. コンテンツのlocal公開

ビルドしてローカルでコンテンツ(まだカラッポですが)を閲覧してみます。

コンテンツの初ビルド

コンテンツをビルドしてみます。

command:

make html

result:

(snip)

build succeeded.

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

コンテンツのlocalhost公開

自分は Mac でのlocalコンテンツを ~/public_html で公開しているので、その下にコンテンツへのシンボリックを張ります。

ノート

Mountain Lion のシステムプリファレンスから "Web共有" が消えたんですね、知らなかった... (UNIX系サーバと同じく apachectl 使うみたいです。)

command:

% pushd ~/public_html/
% ln -s ${TARGET_DOC}/_build/html sample-sphinx

ブラウザで http://localhost/sample-sphinx にアクセスすると、スケルトン状態のコンテンツが見えます。

確認できたら、ドキュメント作業ディレクトリに戻ります。

command:

% popd

4. .hgignore の作成

hg status を実行するとリポジトリに反映されていないファイルのリストが表示されます。

command:

% hg status

result:

A Makefile
A conf.py
A index.rst
A make.bat
? _build/doctrees/environment.pickle
(snip)
? _build/html/searchindex.js
? _themes/tcsh

リポジトリトップ直下に .hgignore を作成して、バージョン管理する必要がないファイルを登録しておきます。

.hgignore:

.sw.$
_build
_themes/tcsh
_warn.log

ノート

.sw.$ は viなどが作成するスワップ系ファイルを除外するために記述します。

.hgignoreファイルもリポジトリで管理します。

command:

% hg add .hgignore

result:

.hgignore を追加登録中

この時点で、リポジトリ未反映ファイルは下記になります。

command:

% hg status

result:

A .hgignore
A Makefile
A conf.py
A index.rst
A make.bat

5. 基本パーツの作成

この段階で、reSTファイルを書いて、local Web で見た目を確認する環境は整いました。

が、Sphinxならではの機能を活かすため、追加で主に下記の作業をしています。

1. 置換テーブルの作成/設定

2. 用語集/用語一覧(Index)の作成

3. 各ページへのリファレンス名の追加

上記以外の調整作業も含めて書いていきます。

5.1. タイトルの編集

sphinx-quickstartが作ったタイトルでは長過ぎるので、書き換えます。

index.rst (diff):

- .. Sphinx Sample Product document documentation master file, created by
-    sphinx-quickstart on Mon Dec 24 11:39:02 2012.
-    You can adapt this file completely to your liking, but it should at least
-    contain the root `toctree` directive.

- Welcome to Sphinx Sample Product document's documentation!
- ==========================================================

+ ==============================================================================
+ Sphinx Sample Product document
+ ==============================================================================

ノート

自分は、最上位の Section Structure は = を 64もしくは78個上下に挟んでいます。

5.2. リファレンス名の追加

トップページへのリンクをどこにでも記述できるようにリファレンス名を追加します。

ファイルの1行目にリファレンス名 'top' を記述して、タイトルとの間に空行を追加します。

index.rst (add):

.. _top:

==============================================================================
Sphinx Sample Product document
==============================================================================

5.3. トップへのリンクの追加

今回はサンプルとして index.rst の末尾に top へのリンクを追加しておきます。

index.rst (add):

:ref:`TOPへ戻る <top>`

5.4. modindexの削除

Pythonistaじゃないので modindexは行削除しています。 (すいません、すいません)

index.rst (diff):

- * :ref:`modindex`

ノート

- Python以外のモジュールは genindex に入ります。

- これが分けられると便利だと思ったり..

5.5. 置換テーブルの作成

Sphinxでは、手順テンプレートの特定文字列を置換して、特定作業の手順書を自動生成することなどが簡単にできます。

自分はこれを多用しているので、最初に置換定義を記述するためのファイルを作成しています。

今回は、とりあえず動作確認用の置換定義だけ入れておきます。

define/defines.txt:

.. |CURRENT_VERSION| replace:: 1.0.0
.. |NEXT_VERSION|    replace:: 1.0.1

ビルドするときに全rstファイルが置換テーブルを参照できるように conf.py に下記を追記します。

conf.py (add):

rst_prolog= u"""
.. include:: /define/defines.txt
"""

ノート

conf.py で絶対パス指定すると、Sphinxドキュメントのルートからの相対指定になるようです。

5.6. 用語集の作成

ドキュメントで用語にゆらぎがあると後で保守が大変なので、最初に用語を書いておく場を用意しています。

今回は、上で作成した置換サンプルが表示されるか確認するための用語サンプルを入れておきます。

define/words.rst:

.. _words:

================================================================
用語の定義
================================================================

.. glossary::

Hello
挨拶の言葉

Current Version
|CURRENT_VERSION|

Next Version
|NEXT_VERSION|

:ref:`TOPへ戻る <top>`

インデックスファイルの toctree に define/words を追記します。

index.rst:

.. toctree::
:maxdepth: 2

./define/words

ノート

ここでは説明の簡略化のため、直接 define/words を記述していますが、大抵は各階層に index.rst ファイルを作成して、:glob: オプションで自動取得させています。

用語へは term ロールでリンクが作成可能です。

今回は index から 定義へのリンクを追記しておきます。 (ついでに 置換も使ってバージョン情報も表示してみました。)

index.rst (add):

----------------------------------------------------------------
hello documentation!
----------------------------------------------------------------

このドキュメントでは :term:`hello` についてドキュメントしていきます。

- :term:`Current Version`: |CURRENT_VERSION|
- :term:`Next Version`:    |NEXT_VERSION|

5.7. コンテンツをビルドしてみる

さて、ここまでのコンテンツをビルドしてみます。

command:

% make html

警告

下記が使えるようになっていることを確認します。

置換

- 置換文字列が、置換テーブルに従って置換されている。

用語一覧(Index)/用語へのリンク

- termロールを記述した用語について、リンクが作成されている。

- indexページの 'Indices and tables' にある Index リンクをクリックすると用語一覧が表示される。

- 用語をクリックすると、用語集のページに遷移し、該当用語がハイライトされる。

リファレンス名/リファレンスリンク

- 用語集の一番下に 'TOP' へのリンクが作成されている。

- リンクをクリックすると、トップページに遷移する。

Search Page

- indexページの 'Indices and tables' にある 'Search Page' リンクをクリックすると検索画面が表示される。

- キーワード(英語のみ 例: Hello)を入力して、'Search'ボタンをクリックすると、キーワードが存在するページの一覧が表示される。

5.8. リポジトリへの登録

この時点で、リポジトリ未反映ファイルは下記になります。

command:

% hg status

result:

A .hgignore
A Makefile
A conf.py
A index.rst
A make.bat
? define/defines.txt
? define/words.rst

未登録ファイルを登録します。

command:

% hg add define/defines.txt define/words.rst

result:

define/defines.txt を追加登録中
define/words.rst を追加登録中

6. 最初のコミット

ここまでで、ひととおりSphinxドキュメントらしい体裁が整ったので、本格的にドキュメントを書き出す前に最初のコミットをしておきます。

command:

% hg commit -m 'created repository'

result:

.hgignore
Makefile
conf.py
define/defines.txt
define/words.rst
index.rst
make.bat
コミット対象リビジョン 0:22155cb1732d

さて、ここまででSphinxなドキュメントを書く準備は整いました。あとは、がしがし書いていくだけですね。

7. ドキュメントの作成

では、具体的なドキュメントの作成について、、、書こうと思いましたが、ちょっと情報過多なので、今日はこれぐらいにしておきたいと思います。

今、自分が使っているディレクティブを中心に簡単に触れます。

7.1. プロダクトドキュメントの作成

literalinclude が非常に使い勝手良いです。

- :language: オプションで言語を指定すると、言語に従ったハイライトがされる。(Pygments)

- Rails では 'ruby' や 'erb' を指定することが多い。

- VBA では 'vbnet' を使う。

reSTソース (code 全体):

.. literalinclude:: ./hello_controller.rb
:language: ruby

HTML出力 (code 全体):

# coding: utf-8

class HelloController < ApplicationController
def index
render :text => 'こんにちは、世界!'
end

#ここから
def view
@msg = 'こんにちは、世界!'
render 'hello/world'
end
#ここまで

def about_author
render :text => Hello::Application.config.author
end
end

- :start-after: と :end-before: で特定ブロックだけ限定したインクルードができる。

- 行番号指定に比べて、インクルード対象範囲がおかしくなりにくい。

- 特定ブロックだけインクルードできるようにコメントに工夫が必要。

- 少々邪魔でも、 start-xxx や end-xxx などのコメントをソースコードに入れておいた方がSphinxからのマッチングは確実。

reSTソース (codeの一部):

.. literalinclude:: ./hello_controller.rb
:language: ruby
:start-after: #ここから
:end-before: #ここまで

HTML出力 (codeの一部):

def view
@msg = 'こんにちは、世界!'
render 'hello/world'
end

- コードが更新された場合でも、buildしなおせば最新のコードに追随できる。

ノート

仕様や要求を reST でまとめ、その仕様ドキュメントにソースコードをliteralincludeする、変更があった場合は Howをソースコードに Why を reSTファイルに残す、が理想なんじゃないかと思っています。

7.2. 運用ドキュメントの作成

include と replace の合わせ技が強力です。

- define/work-manual/ などに、定型作業の手順テンプレートを作成し、変数部分に置換文字列( |HOGE| など)を記述しておく。

define/work-manual/hello.txt:

.. rubric:: 1. login

command:

% ssh |TARGET_HOST|

.. rubric:: 2. ls

command:

% ls

.. rubric:: 3. logout

command:

% exit

ノート

- include先ファイルで Section Structure (見出し) を使うと、include元とコンフリクトするリスクが高いため、 rubric ディレクティブを使っています。

- 置換文字列を使っているブロックで :: によるリテラル化をすると、置換文字列がそのまま表示されてしまうので注意が必要です。Admonitions系のディレクティブを活用するのが吉。

- activity/2012/20121224-hello.rst などに、置換(replace)を定義し includeディレクティブでテンプレートを指定しておく。 (テンプレートの変数部分が置換された手順書が生成される。)

activity/2012/20121224-hello.rst:

==============================================================================
2012-12-24 Hello
==============================================================================

----------------------------------------------------------------
作業手順
----------------------------------------------------------------

.. |TARGET_HOST| replace:: svr1.example.co.jp

.. include:: ../define/hello.txt

ノート

作業後にテンプレートが更新されてビルドされると、手順が最新のものになってしまうことには注意が必要です。 (make textなどでテキスト出力して、チケットに添付するなどがいいかも。)

make text の結果 (_build/text/activity/2012/20121224-hello.txt ):

2012-12-24 Hello
****************

作業手順
====

-[ 1. login ]-

command:

% ssh svr1.example.co.jp

-[ 2. ls ]-

command:

% ls

-[ 3. logout ]-

command:

% exit

8. おわりに

はじめてアドベントカレンダーなるものに参加しましたが、つい書きたいことが多くなってしまって大変でした。が、日頃まとめたいとおもっていて手つかずだったものについて、自分なりにまとめなおす時間が取れた、少しアウトプットできたという点でとても良い経験でした。

来年もより良いドキュメンテーションへの道を探りつつ、Sphinxコミュニティにも積極的に参加していきたいと考えています。

ということで、明日はアドベントカレンダー最終日、Sphinx開発者のGeorg Brandlさん です! Happy Sphinx!!

25日目: Sphinxの過去と、未来

- 著者: Georg Brandl

- 翻訳: @r_rudi, @shimizukawa

- 原文

このエントリーは日本語の Sphinx Advent Calendar 2012 に参加してくれないかというリクエストに応えて書いています。彼らはすごいよ！彼らは今年Sphinx Conferenceを開催して、イベントには 70人もの人たちが集まったんだ！

Sphinx はいまや5歳になってるし、たぶん今までの歴史を振り返り、将来を語るのに良い時期じゃないかな。

このプロジェクトは2007年前半のいつ頃かに始まった。 この投稿 は私がPythonメーリングリストで見つけた中で一番古い。この時、Pythonのドキュメント作成のためのソースはLaTeXで書かれていた。私は科学的な文章を書くときには絶対LaTeXを使うぐらい好きだけど、その時(今もだけど)思ったのは、 LaTeXはコードのドキュメントを書くには適していないってこと。あれは明らかにマークアップ言語ではないし、ドキュメントへの協力を躊躇させてしまう。それで我々はいつもいろんな形式のテキストを受け取るのに苦しんでいたんだ。

また、そのソースは簡単には使えなかったし、HTMLページ(しかもそのHTMLページにはほとんどのユーザにエラーが出ていた)からドキュメントソース中のファイルへのマッピングは分かりにくかった。あ、そのときソースからHTMLに変換するのに使っていたツールチェインについては聞かないで。(これはPython使いがハックしたいと思わない例の4文字の言語と密接に関連してた)

私は、その頃一部で使われ始めていたreStructuredTextとその実装の「docutils」を基盤としたコードを書いて、この状況を変えようとしていた。 reSTはたぶん一番きれいなマークアップ言語ではないだろうけど、その時は (そして今も)いくつかの要求を満たしていたんだ。

- 軽量なマークアップ(シンプルで、読むのに「邪魔」になる文字がない)

- 簡単に拡張できる (codeでもマークアップでも)

- Python実装がある

- Pythonと強い結びつきがある (reSTはいくつかのPEPでマークアップ言語として指定されている)

新しいフォーマット(それと Armin が作った新しい「グリーンな」デザイン) はたくさんの「+1」を受け取り、新しいツールチェインがPython-devで受け入れられた。それで、8月に私はPythonドキュメントをすべて変換したんだ。 (ところで、あれは初期のPython 3000の作業をしてる真っ最中だったんだ。これに関してはまた別の興味をそそられる物語があってね…)いくつかの機能はまだなかったし、チャプター番号の自動採番とか実装に長い時間がかかった機能もあるけどね。

こうしてPythonは素敵で輝いている新しいドキュメンテーションツールを手に入れ、たくさんの人が「うちでも使える？」って聞いてきた。私はそんな反応があるとは思ってもなかった。なんでかというと「古いLaTeXシステム」は公開されていたけれど、誰もそれを使っているようには見えなかったからね [1] 。 (事実、今思い返してみても、誰がLaTeXシステムを使って いた か本当に思い出せないよ。もし覚えていたら教えてね！)

それでも、Pythonicでドキュメント変換を簡単にしたシステムは、良いものを作ったように見えたんだ。すぐにSphinxという名前をつけたプロジェクトが誕生した。今は、他で使われていないもっと良い名前を見つけたいと願ってるけど、その時はpython.orgのWebサイトで使っている "Pyramid" システムとかけてたんだ。 CMU Sphinx と Sphinx search は両方共私は使ったことがあるし、どちらもすごいプロジェクトだ。彼らには謝らなければならないね。 (おもしろいことに、Sphinx searchも「ホルスの目」のロゴを使ってるんだ。いや、私はその時ほんとにそのことを知らなかったんだよ)

そういうことはあるけど、Sphinxはあっという間に人気になり、私はとてもびっくりしたよ。 Sphinxを使っているプロジェクト の 編集履歴 を見てみてよ。Django、numpy、 matplotlibなどのいくつかの大きなプロジェクトはとても早い時期から導入したね。

コードベースをPython用に完全に合わせていたので、全部のPython固有のコードやハードコード文字列を取り除くのにはかなり時間がかかったよ。でも、一旦その作業が終わると、拡張機能を素早く実装できるようになったんだ。 Pythonが使っていないけど他ので使っている一番大きな機能は autodoc だね。私は、autodocはドキュメントの 自動生成 と 手書き との間のほぼ完璧なバランスを取れていると思っているから、とても大事な機能だね。自動生成されたものは大抵醜い獣となり、すでに良く知っているソフトウェアでなければ理解できない程度になる。チュートリアルはソースコードの中にいれたくないから、置き場所がない。手書きのドキュメントは書くのが退屈で山のように書く必要があるけれど、大体の場合これがあるとドキュメントが読みやすくて分かりやすくなるから、個別の解説文はソースコードの中に入れられるようになる。だからPythonはこの方法を取っているんだ。

autodocは理にかなってると思えるこれら両方の様式を兼ね備えている。ドキュメントの全構造を手で書き、必要に応じて解説文を書き、実装の観点からではなく論理的な観点からAPIの説明を分かりやすく並べ変える。それから、各APIのdocstringをドキュメントに埋め込む

この何年かでautodocの他に、たくさんの機能が追加された。コードハイライトは特別な機能ではなくなったね。

- intersphinx で複数のドキュメントをつなぐ

- doctest を含めて、Sphinxから実行できるように

- HTML テーマ は標準のもの以外にもいくつか増えてきたね

- 数式 や ダイアグラム といったメディアのサポート

- TexinfoやePubなどのたくさんの出力フォーマットをサポート

これまでのマイルストーンは ここ で見れるよ。「大きな」 1.0リリースは 2010年に domain の追加とともに行われた。 domainはPython以外の言語へとSphinxの範囲を広げたんだ。でも期待したようには世界全体を取れていない… まだ、ね :)

最近までSphinxはわりと独裁的に開発されていた。あ、それまでも多くの貢献があったんだよ！2010年には、Sphinxにサマーオブコード学生達が何人かやってきて Python 3の移植、国際化、Webアプリケーションインタフェースといった機能を開発してくれたんだ。でも、最終的には私は全ての修正やプルリクエストに目を通してきた。でも、私の大学院生活が始まった時、大量のやるべき事の前に、自分の人生がとても短い時間でしかないことが分かったんだ。

こういった事があって、今年、Sphinxの未来を作っていく開発者のチームを編成したんだ。これまでのところ、以下の人たちにpush権限を与えている。

- Ervin Hegedüs

- Jon Waltman

- Kevin Hunter

- La Min Ko

- Nikolaj van Omme

- Robert Lehmann

- Roland Meister

- 清水川 貴之

私は彼ら全員にとても感謝しています。また、新しい sphinx-dev ML を開発者の連携のために立ち上げ、それまでその名前で利用者向けのサポートを行っていたMLを sphinx-users ML に移した。この開発者チームの編成により物事が動き始め、たくさんのバグといくつかの新機能を搭載した1.2がもうすぐリリースされることになった。

これからどうするのかって？私は機能的には十分だと思っているけど、いつだってなにかしら不足はあるものだね。そう、私と開発者チームはこれからの開発でこんなことを考えている。

- 私が完全な自動化をあんまり好きではないため、自動ドキュメント生成の sphinx-apidocはそんなに頭が良くない。でも、他の人は興味があると思う。

- Autodocはもっとデバッグが簡単になるべき。例えば、中間生成されているreSTにアクセスできるべき。

- 国際化機能はそんなに広く使われていない。おそらく実装にいくつかの欠点がまだあるから。我々は欠点を修正し、できる限り多くの言語に Sphinx自身のドキュメントを翻訳する事で、良い例を作っていきたい。

- Webアプリケーションサポートはもっと簡単に使えるようになるべき。例えばコメントを含めたりユーザーからの提案を簡単にしたり。

- docutilsは数式やコードハイライトなど、Sphinxが開拓してきた多くの機能をサポートしようと成長してきた。私はこういった、違うマークアップで同じ機能を提供している部分を統合したいと思っているよ。

今はこんなところ。メリークリスマス！

索引

検索

検索機能を使うには JavaScript を有効にしてください。

このページからドキュメントを検索できます。キーワードを下のボックスに入力して、「検索」をクリックしてください。入力された全てのキーワードを含むページが検索されます。一部のキーワードしか含まないページは検索結果に表示されないので注意してください。