6

Sphinx autodocを使用して、関数docstringsからfabfileのドキュメントを生成することは可能ですか？

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>
4

2 に答える 2

3

関数にデコレータを適用したためですsetup_development

以下のようにtask関数を更新する必要があります。functools.wraps

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__れた関数またはメソッドの属性を検査することによってドキュメント文字列を取得することに注意してください。

つまり、デコレーターが装飾された関数を別の関数に置き換える場合、元__doc__の関数を新しい関数にコピーする必要があります。からPython 2.5、functools.wraps()行儀の良い装飾関数を作成するために使用できます。

参考文献:

于 2012-01-13T05:01:19.683 に答える
1

モジュールのドキュメントにあるdecorator_applyレシピを使用して、保存された関数シグネチャを含む完全なドキュメントを作成することができました。decorator

""" 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 ソースです。

.. automodule:: myfabfile
   :members:

いくつかのコメント:

shahjapan によって提出された回答では、一般的なケースでドキュメント文字列を保持する方法が説明されていますが、@taskデコレータが外部ライブラリで定義されているという事実には対処していません。

とにかく、 で装飾された関数については、docstring が自動的に保存されることがわかりました@task。以下は、__init__ファブリックのtasks.WrappedCallableTaskクラスのメソッドです。

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

したがって、それはすでにそのまま機能しています（明示的な.. autofunction::ものが必要です）。関数の署名も保持されるようにするために、decoratorモジュールを上記のように使用できます。

アップデート

モジュールを使用すると、decoratorFabric の動作が中断されます (コメントを参照)。ですから、それは結局実現不可能かもしれません。別の方法として、次の修正された reST マークアップをお勧めします。

.. automodule:: myfabfile2
   :members: 

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

つまり、完全な関数シグネチャを含める必要があります。これは、Sphinx のドキュメントでも提案されていることです ( 「これは、メソッドのシグネチャがデコレーターによって隠されている場合に役立ちます。」を参照してください)。

于 2012-02-19T12:33:01.130 に答える