reStructuredText実行ファイル

reStructuredTextでHTMLドキュメントを書こう！

tags:	python,reStructutedText,utility
created:	2006-04-13T10:15:15

reStructuredTextでHTMLドキュメント reStructuredText処理ツールの作成。

概要

いくつかの拡張を reStructuredText 中で使えるようにした reStructuredText処理アプリケーションです。

Graphvizという自動作図
GoogleChartAPIによる各種チャート
コードのシンタックスハイライター

配布ファイル

eggパッケージ

注釈

以前公開していたものと違い、JAVAやBatikへの依存から開放されました。 eggパッケージによる配布で、Linux、Windowsともに動作することを確認しました。 eggは依存パッケージをPyPIから検索します。プラットフォームによっては、いくつかのパッケージを手動インストールしなくてはなりません。

ubuntuでは:

sudo apt-get install python-xxxx

といった感じで。

バイナリインストーラと違い、こちらの方法だと配布ファイルが最小限になります。 Python2.5系とsetuptools0.6.5以降が必要です。

あらかじめ必要なもの

Graphviz 2.16以降ホームサイト

注釈

Graphviz 2.16以降はレンダリングがCairoベースになり、PNG出力が十分美しくなりました。

使い方

ホーム： http://docutils.sourceforge.net/rst.html

簡単な使い方：クイックリファレンス

設定ファイルについては右記参照：コンフィギュレーションの書き方

起動方法

コマンドラインから起動

コマンドラインから起動

C:\Python25\Scripts\rest2html.exe input.txt

とすれば、「input.html」が生成されます。

プラグインについて

「(インストールフォルダ)\plugins」には現状で

graphviz
codeblock

という３つのプラグインを添付しています。

docutilsの仕様に詳しい方はこのフォルダにモジュールを追加することで、 docutilsの機能拡張を行えます。

graphvizサンプル

この拡張はgraphvizというツールに依存しています。

graphvizはdot言語を用いた作図ができます。:

.. graphviz::

  かんじ -> 漢字

といった具合に記述すると

digraph rst2html1 {
かんじ -> 漢字
}

こんな風な図になります。詳しくはgraphvizのサイトを参照。

Sample1

.. graphviz::

  ranksep=1.0
  nodesep=0.5
  edge [fontsize=8, weight=1.5]
  subgraph cluster0 {
    label = "CPU Core"
    color=black
    {rank=same PROCESSOR ALU}
    PROCESSOR -> ALU [label=制御移管]
    ALU -> PROCESSOR [label=制御返却]
    PROCESSOR -> "MEMORY-IF" [dir=back, label="命令フェッチ"]
    PROCESSOR -> "MEMORY-IF" [dir=both, label="読/書"]
    PROCESSOR -> REGISTERS [dir=both, label="読/書"]
    ALU -> REGISTERS [dir=both, label="読/書"]
    REGISTERS [shape=Mrecord, label="{REGISTERS|PC|{<f0> STATUS|zero|carry}|...}"]
  }
  "MEMORY-IF" -> RAM [dir=both, label="読/書"]
  ROM -> "MEMORY-IF" [label=読]
  ROM -> RAM [style=invis]
  {rank=same ROM RAM}

Sample2

.. graphviz::

  start -> 命令フェッチ
  命令フェッチ -> 命令の解釈
  命令の解釈 -> pread
  命令の解釈 -> aread
  subgraph cluster0 {
    label=PROCESSOR
    color=black
    pread [label=データ読込]
    pwrite [label=データ書込]
    pread -> pwrite
  }
  subgraph cluster1 {
    label=ALU
    color=black
    aread [label=データ読込]
    awrite [label=データ書込]
    aread -> awrite
  }
  pwrite -> end
  awrite -> end
  end -> start [label=繰返し]
  {rank=min start[shape=plaintext]}
  {rank=max end[shape=plaintext]}

code-blockサンプル

codeblockはこのサイトのあちこちでも見られるように何種類かのソースコードを色分けしてきれいにHTML化します。

.. code-block:: python

  import sys

  def test(num=10):
    for i in range(num):
      print i

という内容にすると以下のようになります。

import sys

def test(num=10):
  for i in range(num):
    print i

まとめ

reStructuredText は直感的なドキュメントライティングを支援してくれます。

私は表計算などを除いてとにかくドキュメントを書く！といった状況では rest で書いています。

慣れるまでは大変でしたが、慣れると非常にスピーディーにドキュメントを作成できるようになりました。

このサイトもほぼ同機能のrest処理を行っていますので、記事を書き起こすのが非常に楽です。

是非、reStructuredText の爽快なドキュメントライティングを体験してみてください！

PythonMatrixJp

for Pythonista!