Sphinx によるドキュメント作成

2020年10月24日

はじめに

Sphinx による Python のドキュメント作成について。

環境

  • Ubuntu 16.04 LTS
  • Anaconda3 5.2

プロジェクト構成

プロジェクト構成を以下のように想定する。

  • doc_test/
    • docs/ ... ドキュメントを含む
    • doc_test/ ... コードを含む
      • __init__.py

Sphinx によるドキュメント作成

docs に移動。

$ cd doc_test/docs

ドキュメントのひな型を作成する。

$ sphinx-quickstart

いくつか質問されるが、プロジェクト名、バージョン番号、著者名以外は Enter を押せばよい。

API ドキュメントを作成するには、次のようにする。

$ sphinx-apidoc -f -o apis ../doc_test

conf.py を編集する。

sys.path.insert(0, os.path.abspath('..'))

...

extensions = ["sphinx.ext.autodoc"]

HTML のテーマを変えたい場合は、以下の行を変更する。 

html_theme = 'alabaster'

デフォルトの 'alabaster' の他に，'classic' や 'sphinx_rtd_theme' などがある。その他のテーマは こちら を参照。

html_theme を 'alabaster' 以外に変えたらエラーになる場合は、以下の行をコメントにする。 

# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'relations.html',  # needs 'show_related': True theme option to display
        'searchbox.html',
        'donate.html',
    ]
}

目次に内容を追加する。

index.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   apis/doc_test

HTML を作成する。

$ make html

_build/html に HTML ファイルが作成される。

モジュールの警告が出る場合

以下のような警告が出ることがある。

WARNING: autodoc: failed to import module 'plot' from module 'xxxx'; the following exception was raised:
No module named 'matplotlib'

この場合は、conf.py に以下のように追記する。

autodoc_mock_imports = ["matplotlib"]

日本語化

メニューを日本語化するには、以下のように設定する。

conf.py

#language = None
language = "ja"

docstring

Google スタイル、NumPy スタイルへの対応

sphinx は Python の docstring からドキュメントを作ってくれる。引数の説明など特別な書式があるが、コードを直接見たときにコメントが読みにくい問題がある。docstring には Google スタイルや NumPy スタイルといった書き方があるが、sphinx にはその書式を認識させる拡張機能 "napoleon" があり、それを使うには以下のように設定する。

conf.py

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

__init__ の docstring の表示

デフォルトでは __init__ の docstring はドキュメント化されない。これをドキュメント化させるには、以下のように設定する。

conf.py

autoclass_content = 'both'

これは、クラスの docstring と __init__ の docstring の両方をクラスの説明としてドキュメント化するという意味である。こうする代わりに、__init__ の説明をクラスの docstring に書く手もある。

参考