2016-09-08 3 views
1

私は init.py でのpythonパッケージをドキュメント化しようとしていると、それはpydocを介してユーザに表示するために「」「三重の括弧」「」コメントを解析する方法は私には不明です。のPython pydoc

コメントはpydoc出力の名前と説明のセクションのコンテンツを提供するために解析される方法
>>> help(package) 

または

$ pydoc package 

?使用例のような他のセクションもありますか?

答えて

2

のは、このダミーパッケージを考えてみましょう:./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

希望に役立ちます。

1

最初の行には、短い記述(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文字列の長い記述にそのようなセクションを追加することができます。しかし、彼らは標準ライブラリでそれをするように見えないので、例を入れるのが適切な場所ではないかもしれません。

関連する問題