記事の内容

Sphinxのエラーではまりまくったので、
一連の流れを記載しました。

初期設定の手順

インストール

sphinx-rtd-themeというテーマが一番使いやすいと思っているので、
sphinxとsphinx-rtd-themeを一緒にインストールします。

pip install sphinx sphinx-rtd-theme

sphinx-rtd-theme以外で用意されているテーマはこちらで確認可能。
http://ja.dochub.org/sphinx/usage/theming.html

初期ファイルの作成

このようなフォルダ構成を想定しています。

.
├─── src ※docstring含むコード
│
└─── doc ※このフォルダにShinxに必要なファイルが作成される

sphinx-apidocコマンドで必要なファイルを作成できます。
-Fはフルですべて作成するという意味です。
-oの後ろに必要ファイルを作成するフォルダとdocstringが入ったコードのフォルダを指定。
-fはforceオプションで既に存在する場合でも上書きすることが可能です。

必用なファイルの作成

sphinx-apidoc -fF -o ./docs/ ./src/

その他のオプション

詳細は公式ページを参照
https://www.sphinx-doc.org/ja/master/man/sphinx-apidoc.html#options![Something went wrong]()

オプション	意味 align
-F	fullで生成します。指定しない場合はrstファイルのみ生成されます。
-f	出力時に強制上書きをします。
-o	出力先を指定します。
-H	プロジェクト名を指定します。
-A	authorを指定します。
-V	versionを指定します。

conf.pyの設定

docsフォルダの中にconf.pyが作成されているので下記へ変更します。

conf.py

# -- Path setup --------------------------------------------------------------

import os
import sys
sys.path.insert(0, os.path.abspath('../src/')) # docstrigが入っているフォルダ

# -- Project information -----------------------------------------------------

project = 'project' # 表示させたい名前へ変更
copyright = '2022, Author'
author = 'Author'

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc', # この拡張でdocstringを読み込めるようになる
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon', # google, numpy styleのdocstring対応追加
]

language = 'ja' # 日本語設定


# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme' # installしたテーマへ変更

設定した内容でdoctrees,htmlの作成

コマンドプロンプトでdocsまで移動して、下記コマンドを実行

make html

実行すると_buildフォルダにdoctrees,htmlが作られます。

モジュールのimport WARNINGへの対応

ここがはまりポイントでした。
importlib.import_moduleを使用している場合に下記のエラーがでてきました。

WARNING: autodoc: failed to import module 'module_name'; the following exception was raised:
No module named '{folder_name}.-M'

私の場合、sys.argsを使ってimportlib.import_moduleを使用していることが原因でした。
原因となったなったコードは下記です。

from importlib import import_module

file_name = sys.args[1]
import_module(f'{folder_name}.{file_name}')

make htmlを実行時にsys.argsは下記になっています。

['C:\\Users\\{user_name}\\Anaconda3\\Scripts\\sphinx-build', '-M', 'html', '.', '_build']

このエラーをなくすために下記の用にコードを変更しました。

from importlib import import_module
if sys.argv[1] == '-M':
    sys.argv[1] = 'ファイル名'
    file_name = 'ファイル名'
else:
    file_name = sys.args[1]

import_module(f'{folder_name}.{file_name}')

ちなみにファイ名だけど変更してもよさそうですが、
sys.args[1]自体を変更しないとエラーは解消できなかったです。

それとファイルごとに完結させる必要があるので、
sys.pathにimport先のモジュールが含まれていないケースもエラーになるので、注意が必用です。

WARNINGを非表示にする

単純に警告をなくしたい場合はconf.pyにautodoc_mock_imports
を追加すると警告がなくなります。
ただ、警告がなくなるだけでエラーが起きている場合に状態自体が解決されるわけではないです。

autodoc_mock_imports = ['module_name']

公式サイト
https://www.sphinx-doc.org/ja/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

docstringの書き方

私はGoogle Styleで書いています。

上記サイトよりか、こちらにサンプルコードがあるので勉強になりました。
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

おまけ

情報を調べている過程でみたyoutubeコンテンツが面白かったです。
Sphinx はどのように Python コードからドキュメントを生成するのか (tk0miya) [PyCon JP 2020]

参考記事

python書くなら絶対に使いたい2つのドキュメント生成ツール
 Sphinxの使い方．docstringを読み込んで仕様書を生成
 sphinx入門その1 ドキュメントの自動生成