Getting started

Sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reStructuredText or Markdown documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more.

Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx's power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities.

The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you're done here, you can check out the installation guide followed by the intro to the default markup format used by Sphinx, reStructuredText.

For a great "introduction" to writing docs in general -- the whys and hows, see also Write the docs, written by Eric Holscher.

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

The root directory of a Sphinx collection of plain-text 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

ドキュメント構造の定義

Let's assume you've run sphinx-quickstart. It created a source directory with conf.py and a root document, index.rst. The main function of the root document is to serve as a welcome page, and to contain the root of the "table of contents tree" (or toctree). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

reStructuredText ディレクティブ

toctree はreStructuredText ディレクティブ です。ディレクティブというのは、さまざまな用途で使用される、マークアップの要素です。ディレクティブは引数、オプション、コンテンツを持つことができます。

引数 はディレクティブ名の末尾の2つのコロンの後ろに書かれます。それぞれのディレクティブごとに、引数を持つか、持つ場合はいくつか、というのが決まっています。

オプション は引数の後ろに、フィールドリストの形式で書かれます。例えば、 toctree ディレクティブにおいては、 maxdepth というのがオプションにあたります。

コンテンツ はオプションのや引数から空行を一行空けた、その後の内容になります。ディレクティブごとにコンテンツを書けるかどうか、何を書くのか、というのが決まっています。

ディレクティブの一般的な書き方は、 コンテンツの最初の行は、オプションと同じ高さに書く というものです。

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.

参考

Read more about the toctree directive.

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.

For an example, if you are viewing the HTML version, you can look at the source for this document -- use the "Show Source" link in the sidebar.

参考

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 -M html sourcedir outputdir

where sourcedir is the source directory, and outputdir is the directory in which you want to place the built documentation. The -M option selects a builder; in this example Sphinx will build HTML files.

参考

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

You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, use sphinx-autobuild to run the following command:

$ sphinx-autobuild source-dir output-dir

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 latexpdf は LaTeX ビルダー を実行します。その後ユーザ自身がすぐに実行できるようなpdfTexツールチェインを呼び出しす。

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

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++ドメインのように引数の型にリンクを張るなどの言語ごとの特別な機能が追加されることもあります。

参考

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

基本設定

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

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

Keep in mind that the file uses Python syntax for strings, numbers, lists and so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line.

参考

設定 for documentation of all available config values.

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.

参考

sphinx.ext.autodoc for the complete description of the features of autodoc.

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.py の extensions という設定値に '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.

参考

sphinx.ext.intersphinx for the complete description of the features of intersphinx.

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

脚注