記事の内容
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が作成されているので下記へ変更します。
# -- 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 ドキュメントの自動生成