Sphinxを使ってドキュメント整理

# ドキュメント整理

ドキュメントを整理するのにSphinxが良さそうだったので、インストールからビルドまでの流れを紹介する

## Sphinxを使用する

Pythonのモジュールのドキュメントでも使用されていることが多く、そのドキュメントもきれいだったためSphinxを使用する

### インストール

```ps
pip install sphinx
```

バージョンを確認してインストールされているかを確認する

```ps
sphinx-quickstart --version
```

### プロジェクトの作成

まずはdocs_sphinxという作業ディレクトリを作成し、このディレクトリ上で作業していく

```ps
mkdir docs_sphinx
cd docs_sphinx
```

作業ディレクトリに移動した後、`sphinx-quickstart xxx`を実行する。`xxx`というプロジェクトを作成している。対話式で質問されるため、それぞれ回答していく

### ドキュメントのテンプレートを作成

以下を実行して成功すると、`_build`配下に`html/index.html`が作成されるため、それをブラウザで開く

```ps
./make html
```

「Welcome to xxx's documentation!」が表示されれば成功

### テンプレートをオリジナルにしていく

テンプレートを確認した後、自分のものとして編集していくには`docs_sphinx/xxx`配下にある`index.rst`を編集していけばよい

#### docstringを反映させる

`docs_sphinx/xxx`配下にある`conf.py`を修正する

以下を追記すればよい。`os.path.abspath(__file__)`の`__file__`の中には`conf.py`からみてdocstringを表示したいディレクトリへのパスを記載する

```python
import os
import sys
sys.path.insert(0, os.path.abspath(__file__))
```

また、docstringを読み込むために拡張機能を設定する。`conf.py`に以下を追加する

```python
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
```

#### pythonファイルからrstファイルの作成

pythonファイルをrstファイルに変換することでpythonファイルに書いたdocstringを反映することができる

```ps
sphinx-apidoc -e -f -o <ouput dir> <modules dir>
```

- `<output dir>`には、pythonファイルからrstファイルに変換した際に作成されるrstファイルを格納するディレクトリパスを入力する
- `<modules dir>`には、rstファイルに変換したいpythonファイルがあるディレクトリパスを入力する

#### index.rstを編集していく

`toctree`の部分に`/src/test/testpy`を追加すると、その部分にdocstringが反映される

```rst
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   /src/test/testpy
```

#### ビルド

ビルドしてhtmlで出力する。以下のどちらか、もしくは両方実行すればよい。`./make html`の場合はリンクを追っていく形式で出力されるが、`./make singlehtml`の場合は単一ページで出力される。こだわりに合わせて使用すればよい

```ps
./make html
```

or

```ps
./make singlehtml
```

## Appendix

### テーマを変える

```ps
pip install sphinx_rtd_theme
```

を実行した後、`conf.py`の`html_theme`の部分を

```python
html = "sphinx_rtd_theme
```

とするとテーマを変えることができる。上記は一例であり、他にもさまざまなテーマがある。テーマについては「[https://sphinx-themes.org/](https://sphinx-themes.org/)」が参考になる

### 数式の反映

数式を反映させるために以下の`conf.py`を作成した。TeX記法で数式を書く人は参考になると思う

```python: conf.py
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import os
import sys

# srcフォルダにあるpyファイル（関数など）を読み込むために以下を設定する
sys.path.insert(0, os.path.abspath("../src/"))

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Your project'
copyright = 'Your copyright'
author = 'Author'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc', 
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'myst_parser',
    'sphinx.ext.imgmath',
    'sphinx.ext.mathjax',
    'sphinx_math_dollar',
    ]

mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

mathjax_config = {
    'TeX': {'equationNumbers': {'autoNumber': 'AMS'}},
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
    'HTML-CSS': {'availableFonts': ['TeX'], 'preferredFont': 'TeX', 'webFont': 'TeX'},
}

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

language = 'ja'

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

myst_enable_extensions = [
    "dollarmath", 
    "amsmath", 
    "smartquotes",
    ]

imgmath_image_format = 'svg'
imgmath_font_size = 14
imgmath_latex_preamble = r'''
    \usepackage{amsmath}
    \usepackage{mathtools}
'''

html_use_mathjax = True
imgmath_use_preview = False
```