# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hayashier.gitbook.io/article/others/sphinx-get-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.