Sphinxの使い方

## 記事の内容

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が作成されているので下記へ変更します。


```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を使用していることが原因でした。
原因となったなったコードは下記です。


```py
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']
```

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


```py
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
を追加すると警告がなくなります。
ただ、警告がなくなるだけでエラーが起きている場合に状態自体が解決されるわけではないです。

```py
autodoc_mock_imports = ['module_name']
```
公式サイト
https://www.sphinx-doc.org/ja/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

# docstringの書き方
私はGoogle Styleで書いています。

https://google.github.io/styleguide/pyguide.html

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

### おまけ
情報を調べている過程でみたyoutubeコンテンツが面白かったです。
[Sphinx はどのように Python コードからドキュメントを生成するのか (tk0miya) [PyCon JP 2020]
](https://www.youtube.com/watch?v=FJtNT8gbtVQ)

---

### 参考記事

[python書くなら絶対に使いたい2つのドキュメント生成ツール](https://qiita.com/hatsumi3/items/11c5bc835efe713e4767)
[Sphinxの使い方．docstringを読み込んで仕様書を生成](https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844)
[sphinx入門 その1 ドキュメントの自動生成](https://www.python.ambitious-engineer.com/archives/925)