拡張開発最初の一歩

date:

2013/01/01

author:

渋川よしき

拡張開発をするにはもろもろの準備が必要になります。残念ながら、拡張開発に関しては資料が充実しているとは言えない状態です。ソースコードを参照しなければならないケースも多いでしょう。

下記のものがあるのを前提としています。

  • Pythonの知識(必須)

  • Mercurialの知識(オプション)

  • Bitbucketのアカウント(オプション)

  • PyPIのアカウント(オプション)

ここでは、 Rubyドメイン をモデルケースとして説明しています。

ひな形を作る

まずは下記のリポジトリをフォークし、ローカルにクローンしましょう。もし、Bitbucketのアカウントがなく、Bitbucket上でソースコードを管理する予定がない場合、Githubなどを使いたい場合は、Bitbucketのページの右側のペイン内のDownloadと書かれているリンクでダウンロードするのでもかまいません。

https://bitbucket.org/birkenfeld/sphinx-contrib

クローン、もしくはダウンロードが完了したら、このリポジトリに含まれる make-ext.py を実行します。

$ python make-ext.py
Creating a new sphinx-contrib package
Name: sampledomain (←名前を入れる)
Author name: Yoshiki Shibukawa (←作者名を入れる)
E-mail: yoshiki at shibu.jp (←メールアドレスを入れる)
Created new package in directory sampledomain

これで、ひな形ができあがります。 setup.py や、 MANIFEST.in などのファイルもできあがります。

受け入れテストのドキュメントの作成

作成されたひな形のトップに test というフォルダを作り、Sphinxのドキュメントを作ります。

テスト用のドキュメントを実行する場合は、そのフォルダにある sphinxcontrib フォルダを参照する必要があるので、下記のコードを conf.py に追加します。

sys.path.insert(0, os.path.abspath('..'))
extensions = ['sphinxcontrib.sampledomain']

このドキュメントには、これから追加する機能ができあがった場合を想定して文章を書いておきます。

ソースコードを作成

sphinxcontrib フォルダ内にソースコードを置きます。Nameに設定した名前 + .py が良いでしょう。

拡張機能を作成する場合は下記のものを参照することになるでしょう。

例えば、ビルダーの開発をするのであれば、Sphinx本体のビルダーのコードが役に立つでしょう。また、SphinxはDocutilsをベースとして、大規模ドキュメント向けの機能を追加して作られたシステムなので、ドキュメント(XMLのようなツリー構造)のタグを操作して、情報を収集したり、新しいノードを追加する場合はDocutilsや、他に似たようなことをしている拡張機能が役に立ちます。

ドキュメントの作成

作成されたひな形のトップに、 doc フォルダを作り、Sphinxのドキュメントを作ります。

おそらく、 .. rst:directive:: ディレクティブと、 .. rst:role:: ディレクティブを使ったリファレンスと、書き方のサンプルのドキュメントになるでしょう。

ドキュメントの方では、設定ファイルの項目を追加する場合は、Sphinx本体と同じように設定項目用のディレクティブとロールを conf.py で設定すると良いでしょう。

def setup(app):
    app.add_description_unit(
        'confval', 'confval',
        objname='configuration value',
        indextemplate='pair: %s; configuration value')

ライセンスは、BSDライセンスで問題なければ、 sphinxcontrib リポジトリのルートからコピーしていれておきましょう。

また、変更履歴をまとめた、 CHANGES ファイルも作りましょう。中身はreSTフォーマットで記述します。 doc/index.rst で次のように書けば、ライセンスと変更履歴をドキュメントにもコピペする必要がなくなり、変更箇所を一箇所に集約できます。

ChangeLog
=========

.. include:: ../CHANGES

License
=======

.. include:: ../LICENSE
   :literal:

ドキュメント、ライセンス、変更履歴ファイルは MANIFEST.in にも追加しておきましょう。

PyPIへの公開

ドキュメントを確認して、自分のローカル環境でインストールしてのテストも完了したら、PyPIにアップロードして世界中のSphinxユーザが利用できるようにしましょう。

登録名は、 sphinxcontrib-<パッケージ名> がよく使われます。

$ python setup.py register sdist upload

ドキュメントもPyPIサイトにアップします。

$ python setup.py upload_docs --upload-dir=/doc/_build/html/

詳しくは下記の書籍が参考になります。