更新履歴

• 2020年7月19日　Sphinx v3.1.2を基準とした記述に変更しました

Sphinxとは

Sphinxは知的で美しいドキュメントを簡単に作れるツールです．
（公式が自称しています）

例えば，下のようなドキュメントが，pythonのソースコードから生成できます．

以下，このようなドキュメントの生成手順を解説します．

環境

• Windows 10
• Python 3.6
• Sphinx 3.1.2

※Mac, Linuxでも動作しました

Sphinxのインストール

PyPIから

$ pip install sphinx

condaから

$ conda install sphinx

これで，いくつかのsphinxコマンド（sphinx-apidoc，sphinx-autogen，sphinx-build，sphinx-quickstart）が使えるようになります．

ドキュメントを抽出したいpythonファイルの準備

main.pyを作り，以下を記述します．

"""で囲まれた部分がdocstringと呼ばれる部分で，クラスやメソッドの注釈を入れることができます．

docstringの記法にはReStructuredTextスタイル，Numpyスタイル，Googleスタイルなどがありますが，今回はGoogleスタイルで書きます．

class TestClass:
    """Summary line.
    """

    def testfunc(self, x, y):
        """sum

        Args:
            x (int): 1st argument
            y (int): 2nd argument

        Returns:
            int: sum result

        Examples:
            >>> print(testfunc(2,5))
            7
        """
        return x + y

記法に関しては下記を参照．

• GoogleスタイルのPython Docstringの入門
• docstringのstyle3種の例

プロジェクトの準備

作業ディレクトリを作成し，以下のようにディレクトリを構成して先ほどのmain.pyを配置します．

.
├── docs
└── main.py

sphinx-quickstartを使ってプロジェクトを作成します．
コマンドラインで次のコマンドを入力します．

$ sphinx-quickstart docs

（引数で指定されたdocs内に，ファイルが自動生成されます．）

すると，対話形式で質問がきます．

> Separate source and build directories (y/n) [n]:

ソースとビルドのディレクトリを完全に分けるかどうか．
デフォルトだとソースフォルダ内に_buildディレクトリができます．
そのままエンター．

> Project name: hoge
> Author name(s): hogehoge

プロジェクトと作者の名前．
この２つだけは入力しないと Please enter some text. と怒られるので，適当に入力します．

> Project release []:

プロジェクトのバージョン．
1.0.0など，好きなように入力．エンター．

> Project language [en]:

jaで日本語を指定できますが，最終的なドキュメントがあまり好みではなかったので，デフォルトのenでいきます．
何も入力せずエンター．

（enのままでも日本語は使えて，docstring内で日本語を使ってもエラーにはなりません）

対話は以上で，この時点で，以下のディレクトリ構成とファイルが生成されます．

.
└── docs
    ├── Makefile
    ├── _build
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    └── make.bat

conf.pyはこれからドキュメントを生成していく上での設定値が格納されています．

index.rxtはトップページを提供し、toctreeと呼ばれるスクリプトが記述されています．toctreeは複数のファイルを単一の階層構造に結びつける役割を持っています．

make.batはwindowsでhtmlを生成するときに使用しますが，この記事ではコマンドラインからhtmlを生成するコマンドを打つので今回は気にしなくて大丈夫です．

> Separate source and build directories (y/n) [n]:

> Name prefix for templates and static dir [_]:

> Project name: hoge
> Author name(s): hogehoge

> Project release []:

> Project language [en]:

> Source file suffix [.rst]:

> Name of your master document (without suffix) [index]:

> Do you want to use the epub builder (y/n) [n]:

> autodoc: automatically insert docstrings from modules (y/n) [n]:

> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 
> viewcode: include links to the source code of documented Python objects (y/n) [n]: 
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: 
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

conf.pyの編集

ドキュメント生成のための，最小限の設定をします．

読み込むpythonファイルの設定

docs/conf.pyを開き，以下のコードをアンコメントします．

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

conf.pyから見て１つ上のディレクトリ内のpythonファイルを読み込むため，そのpath（../）を指定します．

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

拡張機能の設定

pythonコードのdocstringを読み込む設定をします．
conf.py内の

extensions = [
]

を

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

にします．

sphinx.ext.autodocは，docstringを自動的に読み込むための拡張機能．

sphinx.ext.napoleonはNumpyスタイルかGoogleスタイルのdocstringをパースするための拡張機能です．
（これがないと，改行などがうまく反映されません）

index.rstの編集

後ほど，index.rstからトップページを生成することになります．

トップページで表示したいモジュール（今回はmain）をindex.rst内に追加しておきます．

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

   main

インデントに注意してください．
私の環境ではインデントが１つずれるだけでエラーになりました．

ドキュメントを生成する

まず，pythonファイルからrstファイルを生成します．
コマンドラインで次のコマンドを入力します．

$ sphinx-apidoc -f -o ./docs .

詳細は公式マニュアルを参照してください．

-fはファイルの上書きをONにする設定．
-oは出力先ディレクトリ（今回は./docs）の指定のための設定です．

次に，rstファイルからhtmlファイルを生成します．

$ sphinx-build -b singlehtml ./docs ./docs/_build

詳細は公式マニュアルを参照してください．

今回は単一ページのhtmlファイルを生成したかったので，-bオプションでsinglehtmlを指定しました．
htmlを指定することで，複数ページのhtmlファイルも生成できます．

docs/_build内にindex.htmlが生成されますので，ブラウザで開きます．

これで最低限の文書ができました．

napoleonによるGoogleスタイルの読み込みの詳細は以下を参照してください：

Napoleon - Marching toward legible docstrings

タイトルを変える

index.rstを見ると，

.. hoge documentation master file, created by
   sphinx-quickstart on Sun Sep  2 18:45:37 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to hoge's documentation!
================================

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

   main

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

のようになっていますので，この中の「Welcome to hoge's documentation!」を書き換えて，再度sphinx-buildするとindex.htmlに反映されます．

sphinx_rtd_themeを使う

htmlのデザインを変えてみます．

sphinx_rtd_themeをインストール

$ pip install sphinx_rtd_theme

conf.pyを開いて，html_themeを修正

html_theme = 'sphinx_rtd_theme'

再度sphinx-buildすると，一番上で掲載したようなhtmlファイルが生成されます．

最後に

仕様書が作成できたら，GitHubからWeb公開したり，CIによる自動ビルドなどが使えると便利です．これらについては既に素晴らしいまとめがありますのでご参照ください：

• sphinx でドキュメント作成からWeb公開までをやってみた
• GitLab 10.1 に GitLab CI + GitLab Pages + Sphinx でドキュメントビルド環境を整える