Open3
Python docstringについて
ササノハPythonのdocstringの書き方について
スタイルは次の３つが有名
- reStructuredText（reST）スタイル
- NumPyスタイル
- Googleスタイル
reStructuredText（reST）スタイル
def func_rest(param1, param2):
"""Summary line.
:param param1: Description of param1
:type param1: int
:param param2: Description of param2
:type param2: str
:returns: Description of return value
:rtype: bool
"""
return True
rNumPyスタイル
def func_numpy(param1, param2):
"""Summary line.
Extended description of function.
Parameters
----------
param1 : int
Description of param1
param2 : str
Description of param2
Returns
-------
bool
Description of return value
"""
return True
Googleスタイル
def func_google(param1, param2):
"""Summary line.
Extended description of function.
Args:
param1 (int): Description of param1
param2 (str): Description of param2
Returns:
bool: Description of return value
"""
return True
自動ドキュメント
docstringを解析してドキュメント化するツールがあり、いくつか試したがイマイチだった。
- API以外の網羅的なドキュメントを書けづらい
- 出力されるドキュメンテーションのテンプレートが気に入らない
httpxスタイルdocstring
httpxでは次のようなスタイルが採用されている。
このdocstringはmarkdown互換のスタイルになっている。
def request(
method: str,
url: URLTypes,
*,
params: QueryParamTypes = None,
) -> Response:
"""
Sends an HTTP request.
**Parameters:**
* **method** - HTTP method for the new `Request` object: `GET`, `OPTIONS`,
`HEAD`, `POST`, `PUT`, `PATCH`, or `DELETE`.
* **url** - URL for the new `Request` object.
* **params** - *(optional)* Query parameters to include in the URL, as a
string, dictionary, or sequence of two-tuples.
**Returns:** `Response`
Usage:
```
>>> import httpx
>>> response = httpx.request('GET', 'https://httpbin.org/get')
>>> response
<Response [200 OK]>
```
"""
自動ドキュメント for mkdocs
mkdocsはmarkdownベースでドキュメントを管理できる静的サイトジェネレータである。
拡張機能のmkautodocを利用すると、次のように参照するapi/docstringを指定できる。
::: yourlibrary.attribute
:docstring:
yourlibrary.attribute(param1, *, param2=None)
> docstring line 1
> dcostring line 2
...
mkdocsのスタイルは見栄えがよい。
また、apiのドキュメンテーションは完全な自動でなく参照形式のため、柔軟性が高い。
これにより、api以外のドキュメントとの統合が楽になっている。
デフォルト値は出力するが、アノテーションは出力しないようだ。
理想ではないが、現時点で最も有力なドキュメント方式だと思う。
ササノハmkautodocでドキュメント自動生成時に、genericを上手く認識しないっぽい。
*args, **kwdsになってしまう。。
class A:
def __init__(self, source):
pass
=> OK A(source)
class A(Iterable[T]):
def __init__(self, source):
pass
=> NG A(*args, **kwds)