はじめに
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']
参考記事