更新履歴
- 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
記法に関しては下記を参照．
プロジェクトの準備
作業ディレクトリを作成し，以下のようにディレクトリを構成して先ほどの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を生成するコマンドを打つので今回は気にしなくて大丈夫です．
ソースとビルドのディレクトリを完全に分けるかどうか． Sphinxの作るシステムディレクトリの名前の先頭に付く文字列の指定．デフォルトだと プロジェクトと作者の名前． プロジェクトのバージョン． （ ソースファイルのデフォルトの拡張子．デフォルトだと ドキュメントを生成したときの，トップページのファイル名．デフォルトは エンター． これは エンター連打．Sphinx v1.x 使用時のチェック項目も記載しています．参照するには矢印をクリックして展開してください．
> Separate source and build directories (y/n) [n]:
デフォルトだとソースフォルダ内に_buildディレクトリができます．
そのままエンター．> Name prefix for templates and static dir [_]:
_．
そのままエンター．> Project name: hoge
> Author name(s): hogehoge
この２つだけは入力しないと Please enter some text. と怒られるので，適当に入力します．> Project release []:
1.0.0など，好きなように入力．エンター．> Project language [en]:
jaで日本語を指定できますが，最終的なドキュメントがあまり好みではなかったので，デフォルトのenでいきます．
何も入力せずエンター．enのままでも日本語は使えて，docstring内で日本語を使ってもエラーにはなりません）> Source file suffix [.rst]:
.rst．（reStructuredTextの記法によるテキストファイル，という意味）．
そのままエンター．> Name of your master document (without suffix) [index]:
index
エンター．> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
yでもいいのですが，どうせ後で設定ファイル（conf.py）を編集することになるので，そのままエンター．> 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による自動ビルドなどが使えると便利です．これらについては既に素晴らしいまとめがありますのでご参照ください：