こんにちは、Zero-Cheeseです。
プロジェクトのドキュメント制作、面倒ではありませんか？
本記事では、Python初級者以上を対象に、ドキュメント自動生成ツール「Sphinx」の使用方法を、詳しく解説します。
ドキュメント自動生成には、Docstringの記述が必要です。
Docstringの記述方法に慣れていない方は、近日中に公開予定の関連記事を、本ブログでチェックしてみてください。
Pythonのドキュメントを、自動生成する方法
Sphinxのインストール方法
Sphinxは、pipを使用して、簡単にインストールできます。
pip install sphinxpipの使い方については、以下の関連記事を、ご参照ください。
プロジェクトのセットアップ
ドキュメント生成の準備として、Sphinx用の、「専用フォルダ」を作成します。
プロジェクトのルートディレクトリが乱雑にならないよう、ドキュメント関係は、当フォルダに全て格納します。
フォルダ作成と移動は、以下のコマンドで行います。（カレントディレクトリ：ルートの場合）
mkdir docs
cd docs次に、Sphinxの初期セットアップを行います。
sphinx-quickstartセットアップ時、以下の質問があります。
（例：）
Project name: sphinx
Author name(s): 2023, Nanashi
Project release []: [0.0.1] ⇦ リリースバージョンを指定
Project language [en]: [ja]
conf.pyの編集
conf.pyはSphinxの設定ファイルで、sphinx-quickstartを実行することで、自動生成されます。
基本設定
docs/source ディレクトリに移動して、conf.pyを編集、必要な拡張モジュールを追加します。
extensions = ['sphinx.ext.autodoc']上記の拡張モジュールを設定する事で、Sphinxは、Pythonのソースコードからドキュメンテーションを、直接生成できます。
さらに、Pythonファイルの場所を、適切に指定します。
Pythonファイルがルートディレクトリにある場合は、以下のように編集します。
（conf.py の最上段に、下記コードを追記します。）
import os
import sys
# ルートディレクトリをパスに追加
# この操作にて、ルートディレクトリ直下にある、〇〇.pyが読み込まれます。
sys.path.extend([
os.path.abspath('../..'), # ルートディレクトリ
])上記の設定により、
- ルートディレクトリや、そのサブフォルダ内のPythonファイルが
「Sphinx」によって、探索されます。
新しいモジュールを追加した場合の、ドキュメント生成方法
例として、「new_module.py」の、ドキュメント生成方法を説明します。
「new_module.py」には、下記内容が、含まれているとします。
def example_function():
"""This function does something."""
pass
class ExampleClass:
"""This class represents an example."""
def method_in_class(self):
"""This method does something inside the class."""
pass
ドキュメントを生成するため、
docs/sourceディレクトリ内に、new_module.rstという新しいファイルを作成し、
下記内容を、追加します。
New Module
==========
.. automodule:: new_module
:members:
:members: オプションを使用することで、new_module.py 内の全ての関数やクラスが、ドキュメントに取り込まれます。
Sphinxのエントリーポイント、index.rstの編集
index.rstは、Sphinx-quickstartを実行することで、docs/sourceディレクトリ下に、自動生成されるファイルです。
new_moduleを追加することで、new_module.rstへのリンクが作成されます。
（追加点は、 15行目の、new_module です。）
.. sphinx documentation master file, created by
sphinx-quickstart on Sun Aug 6 13:54:05 2023.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to My Project's Documentation!
==================================
This is the main documentation for My Project.
.. toctree::
:maxdepth: 2
:caption: Contents:
new_module
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
要点
- ヘッダー
(...====) はドキュメントのタイトルを示しています。この場合：”My Project Documentation” - タイトルの下にはドキュメントの概要や説明を、記述します。
.. toctree::ディレクティブは、他のドキュメントへのリンクリストを生成するためのものです。（この例ではnew_moduleというリンクを追加する事で、new_module.rstファイルへのリンクが生成）Indices and tablesセクションは、ドキュメント内の特殊な索引ページや、モジュールの索引ページ、検索ページへのリンクです。:ref:genindex“: 一般的な索引ページへのリンク。:ref:modindex“: Pythonモジュールの索引ページへのリンク。:ref:search“: ドキュメント内での検索ページへのリンク。
ドキュメントの生成
ビルドの実行
docsディレクトリ上で、下記コマンドにて、ビルドします。
make html- ビルドが成功すると、./docs/buildフォルダ下に、ファイル群が生成されます。
- ./docs/build/html/index.htmlをブラウザで開くと、下図のように、生成されたドキュメントを、確認できます。
new_moduleへのリンクを「indices and tables」セクションに追加したい場合:
以下のようにindex.rstを編集します：
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* :doc:`new_module`上記コードを実行結果：
（New_moduleリンクが、追加されている事が、確認できます。）
クライアントにドキュメントを提供する場合、docs/build/htmlディレクトリを、共有します。
docs/build/doctreesディレクトリは、Sphinxがドキュメントをビルドする過程で作られる、中間ファイルです。
無視して問題ありません。
中級者向け：多層フォルダ構造での.rstファイル自動生成方法
中規模以上のソフトウェア開発では、フォルダが多層構造が一般的です。
それぞれのフォルダに手動で.rstファイルを作成し、index.rst に追加するのは、非効率です。
このセクションでは、その作業を自動化する方法について、解説します。
フォルダ構成例
本章では、実務で使用する「フォルダ構成」を例に、自動生成する方法をご紹介します。
例えば、ドメイン駆動開発の場合、以下のようなフォルダ構造を取ることがあります。
project_root/
|-- docs/
| |-- (ドキュメント関連のファイルやディレクトリ...)
|-- domain/
| |-- __init__.py
| |-- models/
| |-- __init__.py
| |-- user.py
| |-- product.py
| |-- services/
| |-- __init__.py
| |-- user_service.py
|-- application/
| |-- __init__.py
| |-- services/
| |-- __init__.py
| |-- user_application_service.py
|-- infrastructure/
| |-- __init__.py
| |-- orm_models.py
| |-- repository.py
|-- interfaces/
| |-- __init__.py
| |-- web/
| |-- __init__.py
| |-- controllers/
| |-- __init__.py
| |-- user_controller.py
| |-- views/
| |-- __init__.py
| |-- static/
|-- tests/
sphinx-apidocは、__init__.pyが含まれるフォルダ（つまり、Pythonのモジュールとして認識されるフォルダ）を、ドキュメントの生成対象として認識します。
したがって、各ディレクトリに__init__.pyが、必要です。
sphinx-apidocの使い方
sphinx-apidocの利用
sphinx-apidocは、Pythonのコードからドキュメントを自動生成するためのSphinxのツールです。
（Sphinxをインストールしたら、併せて当ツールもインストールされます。）
具体的には、Pythonのディレクトリ・ファイル構造に基づいて、.rstファイルを生成します。
sphinx-apidocの使い方は、以下の通りです。
sphinx-apidoc -o [OUTPUT_PATH] [MODULE_PATH][OUTPUT_PATH]:.rstファイルの出力先。[MODULE_PATH]: ドキュメント化するPythonモジュールやパッケージのパス。- -f オプションにて、既存の .rstファイルを上書きできます。
具体例として、カレントディレクトリが「./docs」の場合、下記コマンドとなります。
sphinx-apidoc -o source/ ../ドキュメントの出力
上記コマンドを実行すると、必要なファイル群が docs/source ディレクトリ内に、自動生成されます。
また、自動生成された .rst ファイルには、適切な toctree が含まれています。
生成例：
.. toctree::
:maxdepth: 2
domain/index
application/services/user_application_service
infrastructure/orm_models
interfaces/web/controllers/user_controllerコードの解説：
maxdepth: 2 の設定では、toctreeディレクティブに、直接記載された各ページを基点として、そのページから2階層深い「サブページ」までのリンクを表示します。
つまり、直接リストされているページ（例：domain/index や application/services/user_application_service）は、その階層に関係なく、リンクリストに表示されます。
sphinx-apidoc が出力する内容は、Pythonのモジュールとパッケージのみです。
つまり、特定のディレクトリ構造や、Python外コードのドキュメントを自動で toctree に組み込む場合、追加のスクリプトやカスタマイズが、必要になる場合があります。
index.rstファイルの改廃
トップページである「index.rst」は、自動更新されません。
手動での編集が必要です。
例として、各サブフォルダへのリンクを貼りたい場合、下記のように編集します。
（10〜13行目が、追加点となります。）
Welcome to My Project's Documentation!
==================================
This is the main documentation for My Project.
.. toctree::
:maxdepth: 2
:caption: Contents:
domain
application
infrastructures
interfaces
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`conf.pyの編集
多層ディレクトリ構造の場合、conf.pyを編集して、Sphinxが適切にモジュールを探索できるように、設定する必要があります。
import os
import sys
root_path = os.path.abspath('../..') # ルートディレクトリをsys.pathに追加
sys.path.append(root_path) # ルートディレクトリ以下のすべてのサブディレクトリをsys.pathに追加
for dirpath, dirnames, filenames in os.walk(root_path):
sys.path.append(dirpath)HTML出力
ドキュメントの生成が完了したら、以下のコマンドを実行して、HTML形式で出力します。
cd docs
make html生成されたHTMLファイルは、docs/build/html ディレクトリに、格納されます。
さいごに
現代の開発環境では、頻繁なコード変更に伴い、sphinxのような自動ドキュメント生成ツールが非常に役立っています。
（クライアントによっては、きちんとしたドキュメントを生成する必要がありますが、その場合でも、Sphinxによる自動生成は、活用できます。）
また、Docstringの適切な書き方に関する記事も、近日中に公開予定します！
公開しました。
本記事も、最後までお付き合いいただき、ありがとうございました
それではまた、お会いしましょう！
