Python_ドキュメント生成

pydoc

pydocについて

pydocはpythonをインストールすると標準で付随するドキュメンテーションツールです。

ドキュメントの記法について

docstringには「NumPyスタイル」と「googleスタイル」が推奨されています。

プロジェクトで書きやすい方を選択します。

HTMLドキュメントを作成する。

pythonソースコードを用意します。


$ cat pydoc_test.py

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
# vim:fileencoding=utf-8
# coding=utf8
 
"""
pydocモジュールの練習
"""
__author__  = "authorname"
__credits__ = "Release"
__version__ = "0.01"
__date__    = "5 Oct 2017"
 
class Calc:
    """
    四則演算を行うクラス
    """
    
    def add(self, x, y): 
        """Example function with PEP 484 type annotations.

        The return type must be duplicated in the docstring to comply
        with the NumPy docstring style.

        Parameters
        ----------
        param1 : type
            The first parameter.
        param2 : type
            The second parameter.

        Returns
        -------
        retval: type
            True if successful, False otherwise.
        """
        return x + y

    def sub(self, x, y):
        """引き算メソッド
        引数で指定された値を引き算します。

        Parameters
        ----------
        x : int
            数値を指定します。
        y : int
            引く数値を指定します。

        Returns
        -------
        int:
            引き算した結果の数値を返します

        Examples
        --------
        >>> sub(3, 2)
        1
        """ 
        return x - y

    def mul(self, x, y):
        """掛け算をするメソッド"""
        return x * y

    def div(self, x, y):
        return x / y


def main() :
    """
    本モジュールをコマンドラインから実行するための関数.
    """
    calc = Calc()
    print(calc.add(1, 2))


if __name__ == '__main__':
    main()

ドキュメント化します。モジュール名（ファイル名から拡張子を除く）を指定します。


linux   : $ pydoc -w pydoc_test
windows : > python c:\python36\Lib\pydoc.py -w pydoc_test

sphinx

pythonの有名なドキュメンテーションツールです。

インストール

pipからインストール可能です。


$ pip install sphinx

実行例

ディレクトリ構成を以下のようにします。


├── documents_source/
├── publish/
└── src/
    └── main.py

ドキュメントひな形の生成するために、sphinx-apidocコマンドを実行します。（2回目以降は-Fを-fにします。）


$ sphinx-apidoc -F -o ./doc ./src

doc/conf.pyを編集します。


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

ドキュメントを出力します。


$ sphinx-build -a ./doc ./html

これでhtmlディレクトリ配下にドキュメントが生成さます。