私は init.py でのpythonパッケージをドキュメント化しようとしていると、それはpydocを介してユーザに表示するために「」「三重の括弧」「」コメントを解析する方法は私には不明です。のPython pydoc
コメントはpydoc出力の名前と説明のセクションのコンテンツを提供するために解析される方法>>> help(package)
または
$ pydoc package
?使用例のような他のセクションもありますか?
私は init.py でのpythonパッケージをドキュメント化しようとしていると、それはpydocを介してユーザに表示するために「」「三重の括弧」「」コメントを解析する方法は私には不明です。のPython pydoc
コメントはpydoc出力の名前と説明のセクションのコンテンツを提供するために解析される方法>>> help(package)
または
$ pydoc package
?使用例のような他のセクションもありますか?
のは、このダミーパッケージを考えてみましょう:./whatever/__init__.py
で
./whatever
├── __init__.py
├── nothing
│ └── __init__.py
└── something.py
我々が持っている:
今のpythonシェルを実行している"""
This is whatever help info.
This is whatever description
EXAMPLES:
...
"""
__version__ = '1.0'
variable = 'variable'
:
➜ ~ python
Python 2.7.12 (default, Jul 1 2016, 15:12:24)
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import whatever
>>> help(whatever)
出力は次のようになります。
NAME
whatever - This is whatever help info.
FILE
/home/el/whatever/__init__.py
DESCRIPTION
This is whatever description
EXAMPLES:
...
PACKAGE CONTENTS
nothing (package)
something
DATA
__version__ = '1.0'
variable = 'variable'
VERSION
1.0
説明セクションで提供できる例。だから./whatever/__init__.py
。
希望に役立ちます。
最初の行には、短い記述(PEP 257に記載されているように1行を超えてはいけません)が含まれているように見えます。その後に空白行が続き、段落が続き、DESCRIPTIONセクションにコンテンツを提供するために使用されます。
だから、例えばあなたがjust_to_see/__init__.py
でこれを持っている場合(モジュールと単純な例):
"""A short description
A longer description on several lines etc.
blablabla etc."""
def a_function():
"""
An interesting introductive comment.
Some more explanations.
"""
pass
(hereを述べたように、__doc__
属性のように、ドキュメンテーション文字列を別の場所でできることに注意してください)
その後、pydoc3.4 just_to_see/__init__.py
意志出力:
Help on module __init__:
NAME
__init__ - A short description
DESCRIPTION
A longer description on several lines etc.
blablabla etc.
FUNCTIONS
a_function()
An interesting introductive comment.
Some more explanations.
FILE
/home/nico/temp/just_to_see/__init__.py
あなたのパッケージがインストールされている場合(仮想環境で例えば、pydoc
によって、setup.py
(著者の名前など)からいくつかの情報を見つけることができます。
EXAMPLESセクションをトリガーする方法については不明です。まだ標準のPythonライブラリのpydoc
出力でEXAMPLEセクションのサンプルを見つけることができませんでした(しかし、私はそれらをすべてブラウズしていません)。たぶんあなたは、あなたのパッケージのdoc文字列の長い記述にそのようなセクションを追加することができます。しかし、彼らは標準ライブラリでそれをするように見えないので、例を入れるのが適切な場所ではないかもしれません。