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

はじめに

Sphinxとは

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

PlantUMLとは

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

Sphinx準備

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

test.pyの作成

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

Sphinxのインストール

ライブラリをインストールしてdocsファイルにビルドを行います。

$ pip3 install sphinx
$ sphinx-quickstart docs

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

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のコード全体

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

テーマを変更する

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

$ pip3 install sphinx_rtd_theme

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をしないと反映されない場合もあります。

結果

メインページ

test.pyの内容確認

PlantUMLを組み込む

インストール

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

# 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 (抜粋)

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ファイルに組み込む

  # シーケンス図サンプル
.. 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

#!/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

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

参考記事