Help us understand the problem. What is going on with this article?

SphinxでPythonドキュメントを自動的にビルド

More than 5 years have passed since last update.

はじめに

みなさんこんにちは!Python書いてますか? 現在Python + djangoを使ってサービスを作っているのですが、Pythonistaならお馴染みのとおり、Pythonにはdocstringというのが設定できるのを知っているかと思います。例えば、次のような簡単なスクリプトを動かしてみましょう。

# -*- coding: utf-8 -*-
from __future__ import print_function


def foobar():
    u"これは無意味な関数です。"
    pass


print(foobar.__doc__)

Pythonでは関数、クラス、メソッドで最初に現れた文字列リテラルを__doc__に代入し、あとからその関数の意味について調べることが出来ます。これは便利な機能ではあるのですが、しかしただPythonの対話型コンソール画面やIDE、あるいはPython向けの各種プラグインからしか引用できないとなると、とてももったいない。

そこで、Pythonistaがよくつかう、Sphinxというドキュメントツールを使うと、このDocstringをまとめて一つにしてくれます。そのコマンドがsphinx-apidocです。これの詳しい使い方については、公式ドキュメントを見ていただければと思います。上手くいけば、Sphinxのプロジェクトが立ち上がることでしょう。

さて、テスト駆動をやる上において、watchdogであったり、あるいはsnifferにテストをフックして、ファイルが更新されるたびに、テストを起動している人も多いかと思われます。そこで、自分はdocumentもフックにして自動生成していたりします。

以下はsnifferの例です。

@runnable
def execute(*args):
    from subprocess import call
    call('cd ../docs;make html', shell=True)
    return call(
        'python manage.py test users --failfast',
        shell=True) == 0

Linuxの場合ですと、sphinxは、Makefileを作り、makeコマンドからドキュメントをビルドします。このようにフックを作っておくことによって、常に手元には最新のドキュメントが出来、そして意図しないreStのSyntax的な間違いがチェックできるようになります。

ただ気を付けておくこととしては、Git.gitignoreのファイルとしてドキュメントディレクトリをいれていない場合、非常に鬱陶しいことになります。

もちろん、Pythonのプロジェクトではなく、Sphinxのドキュメント生成性能がとても優秀であるが故に、別の言語のプロジェクトでつかっている人もいるでしょう。また、普通に資料を作るためにつかっている人もいるでしょう。そういうときに、sniffer + sphinxという組み合わせは非常に快適ですので、おすすめです。もちろん、ほかのファイル更新管理ツールを作ってもいいと思います。

esehara@github
本物のプログラマーではないほうを担当しています
http://bugrammer.hateblo.jp/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした