Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
144
Help us understand the problem. What is going on with this article?
@icoxfog417

PythonプロジェクトのドキュメントをSphinxで作成する

More than 5 years have passed since last update.

Pythonのプロジェクトでドキュメントを書く、といったらSphinx、というくらいSphinxはメジャーなツールになっています。そのため、ここではPythonのプロジェクトドキュメントをSphinxで作成する手順について解説します。

Sphinxのインストール

Sphinxについては、日本ユーザー会のサイトで詳しく解説されています。当然、インストールの手順も記載されています。

Sphinx-Users.jp

上記の解説ではeasy_installを使用していますが、pip install Sphinxや、Anaconda/Minicondaを使っていればconda install Sphinxでも導入可能です。

※2015/8/2現在、Sphinxが依存するBabelの最新版2.0ではPython3環境において不具合があります。これを回避するには、一旦pip uninstall babelを実行したのち、pip install babel==1.3でダウングレードするが、GitHub上のブランチから直接インストールしてください(pip install git+https://github.com/mitsuhiko/babel.git@2.0)。

Sphinxはプロジェクト共通で利用するツールなので、virtualenvなどの仮想環境内でなく、グローバルにインストールしておいた方が良いと思います。
※仮想環境内にインストールしてしまうと、プロジェクト本体の依存ライブラリとドキュメントを作るためだけのSphinxの依存ライブラリが混ざってしまい、requirements.txtが冗長になります

ドキュメントの作成

ここから実際にドキュメントを作成していきます。具体例があった方がイメージがつきやすいと思うので、以下にサンプルのリポジトリを用意しました。フォルダ構成やソースの修正箇所などについてはこちらを参照した方がわかり易いと思います。

icoxfog417/python_doc_sample

まず、Pythonプロジェクトの直下にdocsというフォルダを作成し、そこにドキュメントを作成していきます。
作成したdocsフォルダに移動し、sphinx-quickstartを実行し、ひな形を作成します。

sphinx-quickstart

このコマンドの詳細については、こちらのページにある「sphinx-quickstartの詳細説明」を参照してください。

これでドキュメントはの準備は整いました。ただ、APIリファレンスのようなものは当然ソースコードから自動で生成したいものです。Sphinxでは、sphinx-apidocを利用しこのソースコードからのドキュメント生成を行わせることができます。
以下コマンドでは、docsフォルダ内のapisに、Pythonパッケージであるpython_doc_sampleのドキュメントを生成しています(コマンドはプロジェクトのルートから実行)。

sphinx-apidoc -f -o docs/apis python_doc_sample

※importの仕方によっては、importしたものの文書まで芋づる式に作成されてしまうので注意(こちら参照)。

これでプロジェクトに関する文書とAPIリファレンスが整いました。何れも、文書は拡張子が.rstであるreStructuredText形式で書かれています。最終的には、これをHTML形式に変換する必要があります。
そのためのコマンドがsphinx-buildですが、makeを使用する方が簡単です(Windowsでも、sphinx-quickstartを実行した際make.batが作成されるので利用可能です)。

make html

と、コマンドを実行する前にconf.pyを編集しておきます(docsフォルダの直下にあるはずです)。
なぜなら、デフォルトではPythonコードからの自動ドキュメント作成はオンになっていないためです。

conf.py
...
sys.path.insert(0, os.path.abspath('../')) 

...
extensions = ["sphinx.ext.autodoc"]
  • 23行目のあたりにあるsys.path.insertで、作成したPythonパッケージへのパスを通しておきます
  • 33行目あたりのextensionsで、APIドキュメント作成を行うための拡張sphinx.ext.autodocを追加しておきます

conf.pyを修正後make htmlを実行すれば_buildフォルダにHTMLファイルが作成され、以下のようなWebページが参照できると思います。

image

そして、Module Indexのリンクからは、プロジェクト内のパッケージから作成されたAPIドキュメントが検索/参照できると思います。

image

コメントを適切に書いておけば、以下のように見えると思います。

image

以後は、ドキュメント(.rst)の更新をしたらmake htmlでHTMLページが更新されていきます。
ただ、ソースコード側の修正の場合はsphinx-apidocの実行が必要で、これが面倒という場合は簡単なバッチかスクリプトを作ってもよいと思います(サンプル)。

上記で紹介したコマンドは以下にリファレンスがまとまっているので、オプションの意味などを確認する際に参考にしてください。

Sphinx Documentation

ドキュメントの公開

作成したドキュメントはHTMLページなので、サーバーにおけば簡単に公開できます。GitHubリポジトリの場合、GitHub pagesが使えます。

Creating Project Pages manually

HTMLページが作成される_buildフォルダをgh-pagesにpushすればそれで公開は完了です。ただ、注意点として静的ファイルへのアクセスのため.nojekyllファイルが必要な点に注意してください。

これでPythonプロジェクトのドキュメントをSphinxで作成し、公開できるようになりました!

144
Help us understand the problem. What is going on with this article?
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
icoxfog417
All my statements are from fun fancies, not a boring story that represents a company that I belonging to.
tis
創業50年超のSIerです。

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
144
Help us understand the problem. What is going on with this article?