ファブファイル用のスフィンクスオートドックの使用

Question

私のファブファイルのドキュメンテーションを生成するのに、docstrings関数からSphinxオートドックを使用することはできますか？

など。 setup_developmentタスクを含むfabfileについては、私は試しました：

.. automodule::fabfile 
    :members: 
    .. autofunction:: setup_development 

何も生成されません。

fabfileはスニペット：

@task 
def setup_development(remote='origin', branch='development'): 
    """Setup your development environment. 

    * Checkout development branch & pull updates from remote 
    * Install required python packages 
    * Symlink development settings 
    * Sync and migrate database 
    * Build HTML Documentation and open in web browser 

    Args: 
     remote: Name of remote git repository. Default: 'origin'. 
     branch: Name of your development branch. Default: 'development'. 
    """ 
    <code> 

Answer 1

Iは、decoratorモジュールのdecorator_applyレシピfound in the documentationを使用して保存機能シグネチャとの完全なドキュメントを生成することができました。

.. automodule:: myfabfile 
    :members: 

いくつかのコメント：

""" myfabfile.py """ 

from fabric.api import task as origtask 
from decorator import FunctionMaker 

def decorator_apply(dec, func): 
    return FunctionMaker.create(
     func, 'return decorated(%(signature)s)', 
     dict(decorated=dec(func)), __wrapped__=func) 

def task(func): 
    return decorator_apply(origtask, func) 

@task 
def setup_development(remote='origin', branch='development'): 
    """Setup your development environment. 

    * Checkout development branch & pull updates from remote 
    * Install required python packages 
    * Symlink development settings 
    * Sync and migrate database 
    * Build HTML Documentation and open in web browser 

    :param remote: Name of remote git repository. 
    :param branch: Name of your development branch. 
    """ 
    pass 

これは私が使用したシンプルなRESTソースがある

shahjapanが提出した答えは、一般的なケースでのドキュメンテーション文字列を保存する方法について説明しますが、それはありません@taskデコレータが外部ライブラリで定義されているという事実には触れません。

とにかく、で装飾された機能のためにdocstringが自動的に保存されていることが分かります。以下は、ファブリックのtasks.WrappedCallableTaskクラスの__init__方法である：

if hasattr(callable, '__doc__'): 
    self.__doc__ = callable.__doc__ 

それは（明示的.. autofunction::が必要とされている）であるとして、すでに動作するように。ファンクションシグニチャも同様に保持されるように、上記のようにdecoratorモジュールを使用できます。

---

更新

decoratorモジュールの使用は、生地の働きで物事を壊し（コメントを参照してください）。結局のところ実行可能ではないかもしれません。代わりに、次の修正されたreSTマークアップをお勧めします。

.. automodule:: myfabfile2 
    :members: 

    .. autofunction:: setup_development(remote='origin', branch='development') 

つまり、完全な関数シグネチャを含める必要があります。これはSphinxのドキュメントにも示唆されています（"This is useful if the signature from the method is hidden by a decorator.")を参照してください。

Answer 2

そのをあなたの機能にsetup_development

をデコレータを適用したので、あなたが以下のようにfunctools.wrapsであなたのtask機能を更新する必要があり、

from functools import wraps 

def task(calling_func): 
    @wraps(calling_func) 
    def wrapper_func(self, *args, **kw): 
     return calling_func(*args, **kw) 
    return wrapper_func 

あなたの場合ドキュメント装飾された関数やメソッドの場合、autodocはモジュールをインポートしてドキュメントストリングを取得する与えられた関数またはメソッドの属性を検査します。

つまり、デコレータが装飾された機能を別のものに置き換えた場合、元の__doc__を新しい機能にコピーする必要があります。 Python 2.5から、functools.wraps()を使用して、正常に動作する装飾機能を作成できます。

参照：

• Python Sphinx autodoc and decorated members

• http://sphinx.pocoo.org/ext/autodoc.html#directive-autoexception