> For the complete documentation index, see [llms.txt](https://hayashier.gitbook.io/article/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hayashier.gitbook.io/article/others/sphinx-get-started.md).

# Sphinx 導入

## Sphinx 導入

Pythonのソースコードなどのドキュメントを作成するための静的なツールです。\
reStructuredTextで記述してHTMLやPDFとしてドキュメントを出力します。

### 導入

pipを通してSphinxを導入します。`docs/`ディレクトリを作成し、そちらのディレクトリ以下に初期化をします。

```
$ pip3 install Sphinx
$ mkdir docs
$ sphinx-quickstart docs
```

コマンドを実行するにあたって、いくつかインタラクティブに質問されるので、例えば以下のように回答していきます。

```
> Separate source and build directories (y/n) [n]: y
> Project name: my_project
> Author name(s): Me
> Project release []: 0.0.1
> Project language [en]: en
```

先程の最初に質問に`y`で答えると、`docs/`以下に`source/`ディレクトリが作成され、それ以下に`conf.py`が作成されますので、こちらを編集していきます。`n`と答えた場合は`docs/`以下に`conf.py`が作成されます。

```
$ vim docs/source/conf.py
```

`sys.path.insert`を含む以下のコメントアウトされている箇所をコメントを外して、例のように編集します。`../../src/my_project`はサービスが実装されたコードのパスです。

```
import os
import sys
sys.path.insert(0, os.path.abspath('../../src/my_project'))
```

以下になっている箇所を修正後の例のように編集します。

```
extensions = [
]
```

* 修正後

```
extensions = ['sphinx.ext.autodoc','sphinx.ext.viewcode']

# Include Python objects as they appear in source files
# Default: alphabetically ('alphabetical')
autodoc_member_order = 'bysource'
# Default flags used by autodoc directives
autodoc_default_flags = ['members', 'show-inheritance']
```

`setup.py`から実行しない場合は、以下のようにドキュメントを作成します。

```
$ sphinx-apidoc -f  -o ./docs/source src
$ sphinx-build -b html ./docs/source ./docs/build
```

`setup.py`から操作するときは、先程の`sphinx-apidoc`と`sphinx-build`コマンドは実行せず、`setup.py`(もしくは`setup.cfg`)を編集していきます。`setup.py`を編集する場合は、以下を追加します。

```
from setuptools.extension import Extension
import sphinx.ext.apidoc
from sphinx.setup_command import BuildDoc
 
class BuildDocApiDoc(BuildDoc, object):
    user_options = []
    description = 'sphinx'
    def run(self):
        src_dir = 'src/my_project/sample'
        src_dir = os.path.join(os.getcwd(),  src_dir)
        sphinx.ext.apidoc.main(
            ['-f', '-o', os.path.join('docs', 'source', 'modules'), src_dir])
        super(BuildDocApiDoc, self).run()
 
name = 'My-Project'
version = '0.0'
release = '0.0.1'
```

以下のように追加のインストールパッケージとしてSphinx、パッケージの除外対象としてdocsディレクトリを追加します。

* setup\_requires

```
setup_requires=["pytest-runner", "Sphinx"],
```

* packages

```
packages=find_packages(where="src", exclude=("test","docs",)),
```

最後に以下を追加します。

```
cmdclass = {'build_sphinx': BuildDocApiDoc},
command_options={
    'build_sphinx': {
        'project': ('setup.py', name),
        'version': ('setup.py', version),
        'release': ('setup.py', release),
        'source_dir': ('setup.py', 'docs/source'),
        'build_dir': ('setup.py', 'docs/build')}},
```

`setup.py`から実行するときは以下のコマンドを実行

```
$ python setup.py build_sphinx 
```

`.gitignore`に以下を追加しておきます。

```
/docs/build/
/docs/source/modules/
```

`docs/build/index.html`をクリックしてブラウザで開くことで、生成されたドキュメントを確認できます。

* 参考
  * [sphinxでpythonのクラスや関数のドキュメントを自動生成する](https://joppot.info/2018/03/30/4156)
  * [Sphinxによるドキュメント作成と国際化の事始め](https://qiita.com/tatsurou313/items/8bf7b43842b7827760fa)

### Errors

#### checking consistency... /Users/hayshogo/workspace/ElastiCache-ORA-DG/docs/source/modules.rst: WARNING: document isn't included in any toctree

ファイルの先頭に`:orphan:`を追加することでエラーを解消。

* 参考
  * [document isn't included in any toctreeという警告が出る](https://sphinx-users.jp/reverse-dict/system/orphan.html)