使用斯芬克斯車博士的fabfile

是否有可能使用的獅身人面像車博士爲我fabfile生成文檔，從功能文檔字符串？使用斯芬克斯車博士的fabfile

E.g.對於包含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>

來源

2012-01-13 Matt Austin

一個問題是'automodule ::'和'fabfile'之間缺少空格，如果你想使用'..autofunction ::'（ – mzjn 2012-01-13 18:32:23

謝謝，這就是訣竅！看起來像''：members：''不會拾取包裝函數（按照shahjapan給出的答案），所以我可以使用''wraps''或使用''autofunction ::''與''@ task''裝飾器一起工作。 – 2012-01-14 00:50:38

我能夠通過使用decorator_apply配方found in the documentation爲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裝飾在外部庫中定義的事實。

無論如何，事實證明文檔字符串爲飾有@task功能自動保存。以下是在面料的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.")。

來源

2012-02-19 12:33:01 mzjn

這適用於autodoc，但是使用此方法結構不再識別其裝飾任務''fab --list''列出所有函數（這是向後兼容的回退行爲），在這種情況下，更容易忽略' '@任務'完全。當使用''fabfile''作爲模塊時，它還可以防止在其他文件中找到導入的任務。 – 2012-02-20 03:05:53

我想唯一的方法是複製兩個文件中的函數名稱和簽名。有點痛苦，但感謝您的調查。 – 2012-02-26 01:14:50

由於我們還沒有真正找到自動生成fabfile的文檔的方法，因此我在github上爲Fabric創建了一個問題：https：//github.com/fabric/fabric/issues/569 – 2012-02-26 02:53:26

它，因爲你已經在你的函數應用於裝飾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()可用於創建行爲良好的裝飾功能。

參考文獻：

來源

2012-01-13 05:01:19 shahjapan

我不能爲我的生活得到這個工作與現有的''fabric.api.task''裝飾器。你可以提供特定的代碼來修飾這個現有的裝飾器來傳遞''__doc__''？謝謝。 – 2012-01-16 00:23:57

@Matt Austin：所以'autofunction'不起作用用'@ task'畢竟是吧？ – mzjn 2012-01-20 16:20:55

@mzjn autofunction half-works，生成文檔字符串信息，但函數args/kwargs丟失。 – 2012-01-21 02:57:38

使用斯芬克斯車博士的fabfile

回答

相關問題