Sử dụng sphinx autodoc cho một fabfile

Question

Có thể sử dụng Sphinx autodoc để tạo tài liệu cho fabfile của tôi, từ các tài liệu chức năng không?

Ví dụ: cho một fabfile chứa tác vụ setup_development tôi đã thử:

Nhưng không có gì được tạo.

fabfile đoạn mã:

@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

tôi đã có thể sản xuất đầy đủ tài liệu có chữ ký chức năng bảo quản bằng công decorator_apply recipe found in the documentation cho các mô-đun 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 

Đây là nguồn gốc còn lại đơn giản mà tôi đã sử dụng:

.. automodule:: myfabfile 
    :members: 

Một số nhận xét:

Câu trả lời gửi bởi shahjapan giải thích làm thế nào để giữ gìn docstring trong trường hợp chung, nhưng nó không giải quyết thực tế rằng trang trí @task được định nghĩa trong thư viện bên ngoài.

Dù sao, nó chỉ ra rằng chuỗi mã được tự động lưu giữ cho các chức năng được trang trí với @task. Sau đây là trong phương pháp __init__ của lớp tasks.WrappedCallableTask Vải của:

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

Vì vậy mà đã làm việc như nó là (một rõ ràng .. autofunction:: là cần thiết). Để đảm bảo rằng chữ ký chức năng được giữ nguyên, mô-đun decorator có thể được sử dụng như được hiển thị ở trên.

---

Cập nhật

Việc sử dụng các mô-đun decorator phá vỡ mọi thứ trong các hoạt động của Vải (xem bình luận). Vì vậy, điều đó có thể không khả thi sau khi tất cả. Thay vào đó, tôi đề xuất đánh dấu sửa đổi sau đây:

.. automodule:: myfabfile2 
    :members: 

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

Tức là, bạn sẽ phải bao gồm chữ ký đầy đủ chức năng. Đây cũng là những gì được đề xuất trong tài liệu Nhân sư (xem "This is useful if the signature from the method is hidden by a decorator.").

Answer 2

của nó bởi vì bạn đã áp dụng trang trí trên chức năng của bạn setup_development

bạn cần cập nhật chức năng task của bạn với functools.wraps như dưới đây,

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 

Nếu bạn tài liệu được trang trí các chức năng hoặc phương pháp, hãy nhớ rằng autodoc truy xuất tài liệu của nó bằng cách nhập mô-đun và kiểm tra thuộc tính __doc__ của hàm hoặc phương thức đã cho.

Điều đó có nghĩa là nếu người trang trí thay thế chức năng được trang trí bằng chức năng khác, nó phải sao chép bản gốc __doc__ sang chức năng mới. Từ Python 2.5, functools.wraps() có thể được sử dụng để tạo các chức năng trang trí được xử lý tốt.

Tài liệu tham khảo:

• Python Sphinx autodoc and decorated members

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