[python] PyLitの使い方少し

前回の記事で比較・紹介した、文芸的プログラミング用ツール：PyLitの使い方を少し書いておく.

始めよう

この手のツールは解説を読む前に、とにかく始めてしまうのが効率良い方法だ.
また幸い、単にファイルを置くだけなので,インストールでつまずく要素もないと思う.

インストール方法

Downloadリンク先のファイルを、pathの通ったデリレクトリに置くだけ.

コマンドラインツール化

Usage,Installation通りにやれば、問題なくコマンド化できる.
これをやらなくても、置いてスクリプトとして扱うだけで実行できるが、
やっておくにこしたことはないだろう.とても簡単だし.

インストール方法
各種設定方法

その他、各種お好みで設定ができる.

目を通しておきたいドキュメント

Usage, Tutorial, Examples に目を通すだけでも、最低限のことを抑えすぐに使えだせるだろう. 他にも文芸的プログラミングのFAQ的なページもあり、作者のこだわりが感じられる.

主な編集・生成方法

前提

まず前提として、ドキュメントとコードを同じファイルに記述していくシングルソースのアプローチではないことは前回見た.
ファイルは、コードファイルとドキュメントファイル、２つが存在することになるのが、PyLitのアプローチであり、２つのファイル間の整合性をpylitコマンドで担保することとなる.

つまり、.py ⇔ .py.rst(txt)を行き来して、コードと、コードを正しく反映させた文書を書いていく.ただ、実際には.pyでドキュメントとコードをほぼ書き、ドキュメントを整えたい時、コンバートしてreStructured Textを駆使して書いて行くスタイルになるのだろう.
この辺のスタイルについては使って模索していく必要がある.

単純なHelloWorldから始めよう.

コード -> ドキュメント

以下のように、単純なコメント文とコードを記述したファイルを用意する.

view plainprint?

1. # The classical programming example in Python  
2.   
3. print "Hello world."  

# The classical programming example in Python

print "Hello world."

コードファイルからドキュメントファイルへのコンバートは以下のようにする.

$ pylit hello.py
extract written to hello.py.txt

すると、アウトプットファイル hello.py.txt は以下のようになる.

view plainprint?

1. The classical programming example in Python  
2.   
3. ::  
4.   
5.   print "Hello world."  

The classical programming example in Python

::

  print "Hello world."

ドキュメント -> コード

次は、逆の場合だ.
rst-modeなどでドキュメント側をいじりたい場合に、いじった後逆コンバートする使い方になるだろう.

view plainprint?

1. The classical programming example in Python  
2. ほげほげ  
3.   
4. ::  
5.   
6.   print "Hello world."  

The classical programming example in Python
ほげほげ

::

  print "Hello world."

コードファイル側と整合取るには、テキストファイル側を引数にコマンドをたたくだけだ.

$ pylit hello.py.rst
extract written to hello.py

反映後、コードファイル側では以下のように、コメントアウトされた状態で反映される.

view plainprint?

1. # The classical programming example in Python  
2. # ほげほげ  
3.   
4. print "Hello world."  

# The classical programming example in Python
# ほげほげ

print "Hello world."

この辺りはとてもシンプルでイメージする通りの処理と言える.
日本語も問題なく使えた.

ドキュメントブロックとコードブロックの区別

１行のブランク行を持って、テキストブロックとコードブロックを判別している.
そのブランク行以降はコードブロックとして生成され、コメントについては、
ドキュメントテキストではなく、コード上のコメントとしてドキュメントに反映される.

例で見た方が早いだろう.
コードブロックとして生成したい行の前に、ブランク行を入れる.ここでは、Intoroductory~~ からコードとして生成したいという例だ.

view plainprint?

1. # 99bottles.py -- print the famous "99 bottles of beer" song lyrics  
2.   
3. # Introductory example to literate programming  
4. #  
5. # count down from 99 to 1  
6. for bottles in range(99,0,-1):  
7.     ....  
8.       

# 99bottles.py -- print the famous "99 bottles of beer" song lyrics

# Introductory example to literate programming
#
# count down from 99 to 1
for bottles in range(99,0,-1):
    ....
    

これをドキュメントにコンバートすると、以下のように生成される

view plainprint?

1. 99bottles.py -- print the famous "99 bottles of beer" song lyrics  
2.   
3. ::  
4.   
5.   # Introductory example to literate programming  
6.   #  
7.   # count down from 99 to 1  
8.   for bottles in range(99,0,-1):  
9.       ....  

99bottles.py -- print the famous "99 bottles of beer" song lyrics

::

  # Introductory example to literate programming
  #
  # count down from 99 to 1
  for bottles in range(99,0,-1):
      ....

ブランク行以降の、Introductory... からコード上コメントとして生成されている.

view plainprint?

1. # 99bottles.py -- print the famous "99 bottles of beer" song lyrics  
2. #  
3. # Introductory example to literate programming  
4.   
5. # count down from 99 to 1  
6. for bottles in range(99,0,-1):  
7.     ....  

# 99bottles.py -- print the famous "99 bottles of beer" song lyrics
#
# Introductory example to literate programming

# count down from 99 to 1
for bottles in range(99,0,-1):
    ....

このように書けば、

view plainprint?

1. 99bottles.py -- print the famous "99 bottles of beer" song lyrics  
2.   
3. Introductory example to literate programming  
4.   
5. ::  
6.   
7.   # count down from 99 to 1  
8.   for bottles in range(99,0,-1):  
9.       ....  

99bottles.py -- print the famous "99 bottles of beer" song lyrics

Introductory example to literate programming

::

  # count down from 99 to 1
  for bottles in range(99,0,-1):
      ....

ブランク行以降の、count...からコメントとなっている.
ドキュメント上にブランク行を入れたい場合は、２行目のように#だけ記述した状態にしておけばいい.

古い方からコンバートしようとした時のエラー

コンバートを相互に繰り返したとして、時には古いファイルを新しいファイルへコンバートしてしまう可能性があるだろう.そのリスクについては当然アラートを上げ事前対処してくれる.

$ pylit serorde.py
IOError: serorde.py.rst Output file is newer than input file!

他にもオプションいろいろ

• コード部分だけの実行ファイルを作成する、
• あえて上書きする、
• バックアップコピーする

など、やりたくなるであろう各種操作がシンプルなオプション指定により扱える.
とてもシンプルでいて、現実のかゆいところに手が届くオプションを用意してくれている.
usageが参考になる.

今後やりたいこと

コメント部分の肥大化を対処

しっかりしたコメントを加えるアプローチの問題点、コードの見通しが悪くなるという点に対処したい。 -sオプションで、解説部分を除いたコードを生成できるが、編集時の問題は解決されない. 具体的には、コードのたたむelispがあるといいのだけど。

コードを書く／文書を書くスタイルの模索

ツールを使おう という所までは来たものの、
開発効率を落とさず良質なドキュメントも作成できるのかはまったくもってこれからの課題だ.
その目的のためには、このツールを使った開発のスタイル確立が必要だ.
実際の所,ベースは”.pyファイルを編集、コメントをちょっと丁寧に書く”というようなスタイルになるだろう.

つまり、普通にコードを書きつつ、後から文書を仕上げる順序になる.
最初見たように、それだと文芸的ではないが、「ドキュメントを同時に効率良く作成する」
という目的には貢献できると思っている.