はじめに

Once Sphinx is installed, you can proceed with setting up your first Sphinx project. To ease the process of getting started, Sphinx provides a tool, sphinx-quickstart, which will generate a documentation source directory and populate it with some defaults. We're going to use the sphinx-quickstart tool here, though it's use by no means necessary.

ドキュメントのソースの準備

The root directory of a Sphinx collection of reStructuredText document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. 1

Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, run:

$ sphinx-quickstart

Answer each question asked. Be sure to say yes to the autodoc extension, as we will use this later.

sphinx-apidoc; と呼ばれる、自動"API ドキュメンテーション" 生成機能もあります。詳しくは、:doc:`/man/sphinx-apidoc`を参照してください。

ドキュメント構造の定義

もう sphinx-quickstart は実行しましたね? conf.py と、マスタードキュメントの index.rst (もしデフォルトで作成した場合)が含まれる、ソースディレクトリができています。 マスタードキュメント の主な役割は、トップページを提供し、TOCツリー(索引のツリー、もしくは toctree)のルートが置かれています。このTOCツリーというのは、SphinxがreStructuredTextに追加した主要な要素の一つで、複数のファイルを単一の階層構造に結びつける役割を持っています。

The toctree directive initially is empty, and looks like so:

.. toctree::
   :maxdepth: 2

You add documents listing them in the content of the directive:

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

This is exactly how the toctree for this documentation looks. The documents to include are given as document names, which in short means that you leave off the file name extension and use forward slashes (/) as directory separators.

more info さらに詳しい情報については、 toctreeディレクティブ をご覧下さい。

You can now create the files you listed in the toctree and add content, and their section titles will be inserted (up to the maxdepth level) at the place where the toctree directive is placed. Also, Sphinx now knows about the order and hierarchy of your documents. (They may contain toctree directives themselves, which means you can create deeply nested hierarchies if necessary.)

コンテンツの追加

In Sphinx source files, you can use most features of standard reStructuredText. There are also several features added by Sphinx. For example, you can add cross-file references in a portable way (which works for all output types) using the ref role.

例えば、HTMLバージョンの出力を見ているとすると、サイドバーにある"ソースを見る"というリンクを使用すると、ドキュメントのソースを見ることができます。

課題

Update the below link when we add new guides on these.

more info See reStructuredText for a more in-depth introduction to reStructuredText, including markup added by Sphinx.

ビルドの実行

Now that you have added some files and content, let's make a first build of the docs. A build is started with the sphinx-build program:

$ sphinx-build -b html sourcedir builddir

ソースディレクトリソースディレクトリ を、 ビルドディレクトリ はビルドされたドキュメントが置かれるディレクトリを意味します。 -b オプションを使用すると、ビルダーを選択することができます。このサンプルではHTMLファイルを出力するビルダーを選択しています。

more info Refer to the sphinx-build man page for all options that sphinx-build supports.

However, sphinx-quickstart script creates a Makefile and a make.bat which make life even easier for you. These can be executed by running make with the name of the builder. For example.

$ make html

This will build HTML docs in the build directory you chose. Execute make without an argument to see which targets are available.

PDFドキュメントを生成するには?

make latexpdfLaTeX ビルダー を実行します。その後ユーザ自身がすぐに実行できるようなpdfTexツールチェインを呼び出しす。

課題

Move this whole section into a guide on rST or directives

オブジェクトのドキュメントを書く

Sphinxの主な目的の一つが、簡単に ドメイン に属する オブジェクト (非常に一般的な意味です)のドキュメントを書けるようにする、というものです。ドメインというのはお互いに関連する、オブジェクトの型を集めた物です。オブジェクトの説明を作成したり、参照したりできます。

The most prominent domain is the Python domain. For example, to document Python's built-in function enumerate(), you would add this to one of your source files.

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

これは次のようにレンダリングされます:

enumerate(sequence[, start=0])

sequence の要素と、そのインデックスのタプルを生成するイテレータを返します(....など)

ディレクティブの引数は、説明したいオブジェクトの signature です。コンテンツには、それに対するドキュメントそのものを書きます。複数のシグネチャを、1行ごとに書くこともできます。

The Python domain also happens to be the default domain, so you don't need to prefix the markup with the domain name.

.. function:: enumerate(sequence[, start=0])

   ...

もしデフォルトのドメインに対してデフォルトの設定を使い続けたい場合は、同じ事をしてください。

There are several more directives for documenting other types of Python objects, for example py:class or py:method. There is also a cross-referencing role for each of these object types. This markup will create a link to the documentation of enumerate().

The :py:func:`enumerate` function can be used for ...

実際に試してみたのがこれです: enumerate()

繰り返しになりますが、Pythonのドメインがデフォルトで設定されている場合には py: という接頭辞を外して書くこともできます。また、その enumerate() の実際のドキュメントが、どのファイルに書かれているのか、ということを気にする必要はありません。Sphinxが自動で見つけてリンクを張ってくれます。

ドメインごとに、シグニチャをどのように見せることができるのか、というルールは変わってくるでしょう。フォーマットをどのようにきれいに整えたり、C/C++ドメインのように引数の型にリンクを張るなどの言語ごとの特別な機能が追加されることもあります。

more info See Domains for all the available domains and their directives/roles.

基本設定

最初の方で、Sphinxがドキュメントをどのように処理するのかを制御する、 conf.py というファイルがあるということについては軽く紹介しました。このファイルはPythonのソースファイルとして実行され、中に設定値を記述できます。上級のユーザは、Sphinxが処理をする際に、 sys.path を拡張したり、ドキュメントの記述するバージョン番号を取得してくるために、製品コードをインポートして情報を得るような、いくつかの処理を実装するでしょう。

おそらく多くのユーザが変更したがると思われるような設定値については、 sphinx-quickstart を通じて、 conf.py に既に書き込まれ、最初はコメントアウトされた状態になっています(Pythonの標準的な文法で、 # を書くと行の残りの内容がコメントになる)。デフォルト値を変更する場合には、 # 記号を削除して、値を変更してください。 sphinx-quickstart が自動的に追加しない設定値については、設定行を追加してください。

Pythonの文字列、数値、リストなどの文法を利用して設定ファイルを書く必要があります。設定ファイルは、最初の行のエンコーディング宣言の通り、デフォルトではUTF-8形式で保存されます。文字列の値として、非アスキー文字をしようしたい場合には、Pythonのユニコード文字列(例: project = u'日本語版Expose')を使用する必要があります。

more info See 設定 for documentation of all available config values.

課題

Move this entire doc to a different section

Autodoc

When documenting Python code, it is common to put a lot of documentation in the source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an extension (an extension is a Python module that provides additional features for Sphinx projects) called autodoc.

In order to use autodoc, you need to activate it in conf.py by putting the string 'sphinx.ext.autodoc' into the list assigned to the extensions config value. Then, you have a few additional directives at your disposal.

例えば、 io.open() という関数に関するドキュメントであれば、次のように記述すると、シグネチャやdocstring情報はソースファイルから読み取ります:

.. autofunction:: io.open

autodoc関連のディレクティブのmembersオプションを利用すると、クラスやモジュールの要素のドキュメントを自動的に作成することもできます:

.. automodule:: io
   :members:

autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to sys.path in your conf.py.

警告

autodoc はドキュメンテーションされるモジュールを インポート します. もしインポートによる副作用があれば、 sphinx-build が実行されるとき autodoc により実行されます。

もしあなたが (ライブラリモジュールではなく) スクリプトをドキュメント化したいのであれば、スクリプトのメインルーチンが if __name__ == '__main__' 条件により保護されていることを確認して下さい。

more info autodoc機能の完全な説明は、 sphinx.ext.autodoc の説明を参照してください。

課題

Move this doc to another section

Intersphinx

Many Sphinx documents including the Python documentation are published on the Internet. When you want to make links to such documents from your documentation, you can do it with sphinx.ext.intersphinx.

intersphinxを使用するためには、 conf.pyextensions という設定値に 'sphinx.ext.intersphinx' という文字列を追加して、この機能を有効化した後、 intersphinx_mapping という設定値を設定する必要があります。

例えば、 Pythonライブラリマニュアルに含まれる io.open() へリンクするには、次のように intersphinx_mapping をセットアップする必要があります:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

And now, you can write a cross-reference like :py:func:`io.open`. Any cross-reference that has no matching target in the current documentation set, will be looked up in the documentation sets configured in intersphinx_mapping (this needs access to the URL in order to download the list of valid targets). Intersphinx also works for some other domain's roles including :ref:, however it doesn't work for :doc: as that is non-domain role.

more info intersphinx機能の完全な説明は、 sphinx.ext.intersphinx の説明を参照してください。

さらに説明すべきトピック

脚注

1

This is the usual layout. However, conf.py can also live in another directory, the configuration directory. Refer to the sphinx-build man page for more information.