Sphinx+PlantUMLを使ってPythonドキュメントを生成する

# はじめに
## Sphinxとは
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/342722/215f352c-6db6-d277-cea7-3a95ab9a43ed.png)

ドキュメンテーションビルダーのツールになります。
ドキュメント作成ツールは様々あると思いますが、Pythonで書かれたソースコードなどのコメントなどから自動でドキュメントを生成できます。また、Markdown記法、Jupyter Notebook形式などにも対応しているため、そのプロジェクトのドキュメント作成に向いています。
**機能としては様々ありますが、今回は既存のプロジェクトからドキュメントを生成する初歩的な使い方を紹介します**

## PlantUMLとは
ダイアグラムを素早く作成するためのコンポーネントです。

https://plantuml.com/ja/

# Sphinx準備
ローカルにpythonの環境があることが前提になります。

## test.pyの作成
`TEST`プロジェクトを作成して、その直下に`test.py`を作成してください。
[test.pyのコード全体](#testpy)


## Sphinxのインストール

ライブラリをインストールして`docs`ファイルにビルドを行います。
```
$ pip3 install sphinx
$ sphinx-quickstart docs
```

以下のような構造になります。

```name:TESTプロジェクトのtree
.
├── docs # sphinx-quickstartで作成されたディレクトリ
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst
└── test.py # 作成したファイル
```

# ドキュメントの生成
##  rstファイルの作成
.rstファイルを生成します。

```
$ sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>
```

実際のコマンド例
```
$ sphinx-apidoc -f -o docs/source ./
```

```
.
├── __pycache__
│   └── test.cpython-310.pyc
├── docs
│   ├── Makefile
│   ├── build
│   │   ├── doctrees
│   │   └── html
│   ├── make.bat
│   └── source # 追加されている
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       ├── modules.rst
│       └── test.rst
└── test.py
```

## conf.pyの編集

自動生成する際には`conf.py`に下記コードを追加します。
[conf.pyのコード全体](#confpy)

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

### テーマを変更する
テーマを変更して見た目を変更することができます。今回は`sphinx_rtd_theme`を使用します。

```
$ pip3 install sphinx_rtd_theme
```

```python
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme' # ここを変更
html_static_path = ['_static']
```


## index.rstを編集する

```
.. TEST documentation master file, created by
   sphinx-quickstart on Thu Feb  2 14:30:31 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to TEST's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules # 記載無ければ追記する


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
```


# HTMLとして出力してページを確認する

htmlファイルを作成して、openすることで内容をみることができます。
```
$ cd docs
$ make html
$ open ./build/html/index.html
```

編集したら都度`make clean`をしないと反映されない場合もあります。

# 結果

## メインページ
![](https://i.imgur.com/W1YN4tO.png)

## test.pyの内容確認
![](https://i.imgur.com/yGiSN8L.png)


# PlantUMLを組み込む

### インストール
```terminal
# Javaをインストール
$ sudo apt -y install default-jre
Graphvizをインストール
$ sudo apt -y install graphviz
```

```terminal
# PlantUML本体

 # Download
   $ wget 'https://downloads.sourceforge.net/project/plantuml/plantuml.jar?r=http%3A%2F%2Fplantuml.com%2Fstarting&ts=1538667739&use_mirror=jaist'

 # Rename(名前は違う可能性あり)
   $ mv 'plantuml.jar?r=http:A%2F%2Fplantuml.com%2Fstarting&ts=1538667739&use_mirror=jaist' plantuml.jar

 # move
   $ sudo mv plantuml.jar /usr/local/bin/
```

### conf.pyを編集

docs/source/conf.py (抜粋)

```python
extensions = [
	'sphinx.ext.autodoc',  # ソースコード読み込み用
	'sphinx.ext.viewcode',  # ハイライト済みのソースコードへのリンクを追加
	'sphinx.ext.todo',  # ToDoアイテムのサポート
	'sphinx.ext.napoleon',#googleスタイルやNumpyスタイルでdocstringを記述した際に必要
 	'sphinxcontrib.plantuml' # sphinxcontrib.plantuml モジュールを読み込む
	]
plantuml = 'java -jar /usr/local/bin/plantuml.jar' # plantuml.jarのパス
```

### rstファイルに組み込む

```python
  # シーケンス図サンプル
.. uml::
   :scale: 50 %
   :align: center

   @startuml

      actor User

      User -> Form : Input user information
      activate Form
      Form -> Database : Register user information
      activate Database
      Form <- Database : Inform success
      deactivate Database
      User <- Form : Show success message
      deactivate Form

   @enduml

 # 直下にある '.pu' ファイルからUMLを読み込む場合
.. uml:: sequence_diagram.pu
   :scale: 50 %
   :align: center

```

# (おまけ)VS codeに入れておくと便利なもの
拡張機能を入れておくとプレビューできて便利です。
* Markdown All in One (Markdownプレビュー)
* PlantUML (PlantUMLプレビュー)
* reStructuredText (rstプレビュー)
* Live Preview (HTMLのプレビュー)

# (参考)コード全体

## test.py
```python
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""モジュールの説明タイトル

* ソースコードの一番始めに記載すること
* importより前に記載する

Todo:
    TODOリストを記載
    * conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
    * conf.pyの``todo_include_todos = True``にしないと表示されない

"""

import json
import inspect

class testClass() :
    """クラスの説明タイトル

    クラスについての説明文

    Attributes:
        属性の名前 (属性の型): 属性の説明
        属性の名前 (:obj:`属性の型`): 属性の説明.

    """

    def print_test(self, param1, param2) :
        """関数の説明タイトル

        関数についての説明文

        Args:
            引数の名前 (引数の型): 引数の説明
            引数の名前 (:obj:`引数の型`, optional): 引数の説明.

        Returns:
            戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)

        Raises:
            例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )

        Yields:
            戻り値の型: 戻り値についての説明

        Examples:

            関数の使い方について記載

            >>> print_test ("test", "message")
               test message

        Note:
            注意事項などを記載

        """
        print("%s %s" % (param1, param2) )

if __name__ == '__main__':

    test_object = testClass()
    test_object.print_test("test", "message")

```

## conf.py
```python

import sphinx_rtd_theme
from recommonmark.parser import CommonMarkParser
import sys
import os

# 自動生成するときは下記記述する
sys.path.insert(0, os.path.abspath("../.."))

project = 'TEST'
copyright = '2023, taitai'
author = 'taitai'
release = '0.1'

extensions = [
	'sphinx.ext.autodoc',  # ソースコード読み込み用
	'sphinx.ext.viewcode',  # ハイライト済みのソースコードへのリンクを追加
	'sphinx.ext.todo',  # ToDoアイテムのサポート
	'sphinx.ext.napoleon',#googleスタイルやNumpyスタイルでdocstringを記述した際に必要
 	'sphinxcontrib.plantuml' # sphinxcontrib.plantuml モジュールを読み込む
	]
plantuml = 'java -jar /usr/local/bin/plantuml.jar' # plantuml.jarのパス


templates_path = ['_templates']
exclude_patterns = []

source_suffix = ['.rst', '.md']


source_parsers = {
    '.md': CommonMarkParser,
}


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

```

# 参考記事

https://qiita.com/pashango2/items/d1b379b699af85b529ce

https://hesma2.hatenablog.com/entry/2021/04/03/180206#%E5%AE%8C%E6%88%90%E3%82%A4%E3%83%A1%E3%83%BC%E3%82%B8

https://kawa-xxx.jp/2020-07-11-213853/