Использование sphinx autodoc для fabfile - PullRequest
Новая
       4

Использование sphinx autodoc для fabfile

6 голосов
/ 13 января 2012

Можно ли использовать автодок Sphinx для генерации документации для моего fabfile из строки документации?

например. для fabfile, содержащего задачу setup_development, которую я пробовал: 

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

Но ничего не генерируется.

Фрагмент файла: 

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

Ответы [ 2 ]

3 голосов
/ 13 января 2012

Это потому, что вы применили декоратор к своей функции 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() может использоваться для создания хорошо оформленных функций украшения.

Ссылки:

1 голос
/ 19 февраля 2012

Мне удалось создать полную документацию с сохраненной сигнатурой функции с помощью рецепта 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 определен во внешней библиотеке.

В любом случае получается, что строка документации автоматически сохраняется для функций, украшенных @task.Ниже приведен метод __init__ класса Fabric tasks.WrappedCallableTask: 

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

Так что это уже работает как есть (необходим явный .. autofunction::).Чтобы гарантировать сохранение сигнатуры функции, можно использовать модуль decorator, как показано выше.

Обновление

Использование модуля decorator нарушает работу Fabric (см. Комментарий).Так что это может быть невозможным в конце концов.В качестве альтернативы я предлагаю следующую модифицированную разметку reST: 

.. automodule:: myfabfile2
   :members: 

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

То есть вам придется включить полную сигнатуру функции.Это также то, что предлагается в документации Sphinx (см. «Это полезно, если подпись метода скрыта декоратором.») .

...