SphinxでPythonコードのdocする自分用メモ

この記事は

Sphinxを使って、Pythonコードをdocumentationする自分用ノート。
下記にとても素晴らしい記事があります。
- Sphinxの使い方．docstringを読み込んで仕様書を生成

仮想環境

createする

# 仮想環境名 sphinx_test ですすめていく
conda create -n sphinx_test python=3.6

activateする

conda activate sphinx_test

sphinxパッケージのインストール

pip install sphinx

documentプロジェクトの初期化

# docsフォルダを作業スペースにする
sphinx-quickstart docs

• いくつか設定に関する質問が出てくるが、デフォルト値のままでよければ Enterキー を押していけばよい
• 下記の設定は任意
  • "project name:"
  • "Author name(s):"
  • "Project release []"

document作成ののconfiguration

• docs/conf.pyを開く

- 下記の箇所のコメントアウト解除

import os
import sys
sys.path.insert(0, os.path.abspath('../'))
# 上のディレクトリに置いたpyファイルを参照したいのでこうする
# os.path.abspath('./') => os.path.abspath('../')

extensionの設定

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

ここでいちどドキュメントをmakeしてみる

.\docs\make singlehtml

pyファイルからrstファイルを生成する

# "."を見落とさないように。ディレクトリ内のすべてのファイルの意味。
sphinx-apidoc -f -o .\docs .

index.rstの変更

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

   TestClass # <- 追加したいpythonファイル　

Pythonファイルを置く

- sphinx_test
    - docs
    - TestClass.py <-- ここに置く

• docstring形式でドキュメントしたいコメントを書く

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

ドキュメントのmake

• さっきと同じ

.\docs\make singlehtml