たのしいドキュメンテーション

日本 XP ユーザグループ代表 ( 予 )Python 温泉 ( 系 ), とちぎ Ruby

渋川よしき

For BPStudy #30, Feb,26th,2010

本日のレシピ• 座学– Sphinx の歴史– Sphinx とは何か？– Wiki との比較– Sphinx の使い方

• ハンズオン– おすすめ書籍紹介ドキュメントを作ってみよう

• 座学– 大きなドキュメントを書くための機能– 技術ドキュメントを書くコツ– Sphinx の内部構造– 1.0 以降の展開

Sphinx のインストール

• Linux/MacOSX な人– sudo port install py26-sphinx など

• Windows な人– Python をインストール– easy_install をインストール– easy_inatall sphinx

詳しくは : http://blog.shibu.jp/article/32044108.html

Sphinx の使い方 - 流れ -

• sphinx-quickstart– django-admin とか、 rails コマンド

みたいなもの– 質問に答えるとフォルダができる

• ドキュメントを作る

• make XXX– HTML– PDF など

プロジェクト作成

ドキュメント作成

ビルド

Sphinx の使い方を調べるには？

• Sphinx 本体の解説– http://sphinx.shibu.jp/

• reStructuredText– Sphinx 内の入門

• http://sphinx.shibu.jp/rest.html

– reStructured 入門• http://www.planewave.org/translations/rst/quickstart.ja.

html

– はやわかり reStructuredText( リファレンス )• http://www.planewave.org/translations/rst/quickref.html

• Sphinx を使っているサイト– コード見れます

Taken by andercismoUnder CC BY-NC-SA

プロジェクトを作ろう

• sphinx-quickstart コマンドで作る–プロジェクト名、著者名、バージョン以外は

Enter 連打で OK– conf.py を必要に応じて編集すればよい

• 既存のスケルトン–自分のいつも使うスタイルを–例： @MiCHiLU さんの sphinx-skeleton

プロジェクト作成

http://bitbucket.org/MiCHiLU/sphinx-skeleton/overview/

• プレーンテキストのマークアップ– reStructuredText を利用• ソースのままでも可読性が高い• 拡張可能なフォーマット

–注意点• 日本語には UTF-8 で使おう• すべての異なる要素の間には空行を

– リストの階層が変わる時も

ドキュメント作成 ドキュメントを作ろう

セクションタイトル• ドキュメントを構成する重要な要素• #, *, =, -, ^, ~, “ などの記号で下だけ、上下を囲う

– 自分なりのルールを決めておくと良い• 単体のソース内の登場順で H1, H2, H3.. が決まる• 文字長よりも短いと警告が出ます

========はじめに========

想定読者========

新人社会人----------

はじめに

想定読者

新人社会人

ドキュメント作成

親子関係の定義• Sphinx の一番重要な部分 ( 大規模ドキュメント作成時 )• toctree ディレクティブを使って定義する

– 拡張子なしのファイル名を列挙する– 目次がその場で作られる (:maxdepth: でレベルが変わる )

• 目次を出したくない場合には、 :hidden: をつけて、 :doc: ロールで自分で索引を作る

.. toctree:: :maxdepth: 2

preface overview/index defensive/index

はじめに 本書の考えるゴール 本書を作るにあたって 本書で説明していくこと

つまみぐい勉強法 勉強はつまみぐいから 大切なことは、継続 自分に合うものを選ぼう 終着点は自分で決めよう

ドキュメント作成

親子関係の定義

• セクションタイトルを子供の文書から引っ張ってきて目次を作る

• toctree 自体は 1 文書に何個も書ける• toctree 表示位置に、子供の文書のセク

ション構造が挿入される

toctree を制するモノが Sphinx を制す

ドキュメント作成

箇条書き• * を前に付けると、バレットリスト• #, 数値 + ピリオドで、ナンバー付きリスト• 複数階層もできます

– ただし階層が変わる前後は空行を入れること

1. トヨタ

* プリウス * クラウンハイブリッド

2. ホンダ

* シビックハイブリッド * CR-Z

1. トヨタ プリウス クラウンハイブリッド

2. ホンダ シビックハイブリッド CR-Z

ドキュメント作成

フィールドリスト• : 項目名 : 値• 著者名、出版日などの情報を列挙したいけど、表にす

るまでもない時に使えます

: 書名 : スクラム : 訳者 : スクラムエヴァンジ .. : 出版社 : ピアソン : 発行日 : 2003/09/20 : 本体価格 : 2000 円 :ISBN: 9784894715899

書名 : スクラム訳者 : スクラムエヴァンジ ..出版社 : ピアソン発行日 : 2003/09/20本体価格 : 2000 円ISBN: 9784894715899

ドキュメント作成

画像• .. image:: ディレクティブで画像を挿入できます• :: の後ろにファイル名を書きます• ファイル名は相対パスもしくは、ドキュメントのルー

トからの絶対パスで指定します

.. image:: image/tornado.png

ドキュメント作成

外部リンク• ` リンクテキスト <http:// ターゲット URL>`_

– 最後のアンダースコアを忘れないように– 日本語の文書の中に挿入する場合は、前後にスペース ( もしく

は ¥ + スペース ) を入れる• URL をそのまま入れる

– リンク張ってくれます

分からないことがあったら `ぐぐって <http://www.google.com>`_ ください

参考 : http://sphinx.shibu.jp

わからないことがあったら ぐぐって ください

参考 : http://sphinx.shibu.jp

ドキュメント作成

表 (1)• 書き方が 4通りあります

– 一番複雑な方法• 縦、横のセルの結合ができます• 文字数が変わると編集が面倒

+-------------+----------------------+---------+---------+------+| Feature List | Python2 | Python3 | Ruby |+=============+======================+=========+=========+======+| Push API | following_function | O | O | |+ +----------------------+---------+---------+------+| | following | O | O | O |+-------------+----------------------+---------+---------+------+| Pull API | Queue | O | O | _ |+-------------+----------------------+---------+---------+------+

ドキュメント作成

表 (2)

• ややシンプルな方法– 縦のセルの結合はできません– 文字数が変わると編集が面倒

• list-table ディレクティブ– かんたんだけど、複雑な制御はで

きない

======= ==== ==============入力 出力------------ --------------種類 引数 索引======= ==== ==============single: A; B A -> Bsingle: A Apair: A; B A -> B, B -> A======= ==== ==============

.. list-table:: 仕様 :widths: 15 10 10 :header-rows: 1

* - 主要諸元 - MXB - MX * - 車両重量 - 1260 - 1270

ドキュメント作成

表 (3)

• csv-table ディレクティブ– かんたんだけど、複雑な制御

はできない

.. csv-table:: 郵便番号 :header: “ 番号” ,“住所” :width: 15, 20

“321-0911”,”宇都宮市問屋町 “321-0912”,”宇都宮市石井町” “321-0923”,”宇都宮氏下栗町”

ドキュメント作成

ノート、引用、コードサンプル

• ブロックを挿入するために各種ディレクティブ、 :: 記号を使う• インデントが終わるまで、ブロックとして扱われる• ブロック

– .. note::, .. tips::, .. warning::, :: 記号など

• コードサンプル– .. code-block:: ディレクティブを使う

.. note::

バージョンにより異なります

.. code-block:: python

@auto_twitter("function") def sample_function(): print “do action”

バージョンにより異なります

@auto_twitter("function")def sample_function(): print ”do action"

ドキュメント作成

ビルド

• コンソールから make html とタイプ• _build/html フォルダ以下に出力されま

す

ビルド

本日のレシピ• 座学– Sphinx の歴史– Sphinx とは何か？– Wiki との比較– Sphinx の使い方

• ハンズオン– おすすめ書籍紹介ドキュメントを作ってみよう

• 座学– 大きなドキュメントを書くための機能– 技術ドキュメントを書くコツ– Sphinx の内部構造– 1.0 以降の展開

ハンズオン (30 分 )おすすめ書籍紹介ドキュメントを作ってみよう

• 二人一組になってください– Sphinx インストールが完了していない人は完了し

ている人とペアを作ってください– 効率を重視する場ではないのでエディタ論争は禁止

• 説明した機能をどんどん使って見ましょう– 練習のために１冊 1 ファイルで。目標は 2冊。– 分からないことがあれば聞いてください