Làm thế nào tôi có thể tạo ra một tài liệu giống như vạm vỡ?

Question

Tôi đang làm việc rất nhiều với spyder và thanh tra đối tượng, mà tôi thấy khá thuận tiện như một chức năng trợ giúp tức thời. Một số mô-đun dường như lợi nhuận rất độc đáo từ chức năng này. Ví dụ một hàm NumPy khá cơ bản (numpy.absolute) tạo ra các điểm sau trong thanh tra đối tượng:

Tôi muốn biết, làm thế nào tôi có thể viết các module của riêng tôi theo cách như vậy, rằng đó là một xem đẹp được sản xuất khi tôi gọi chức năng của tôi trong spyder.

Answer 1

Để tài liệu của bạn hiển thị độc đáo như hình ảnh gọn gàng, bạn cần tuân theo tiêu chuẩn NumpyDoc. Giả sử bạn có một chức năng gọi là func với hai đối số như thế này:

def func(arg1, arg2): 
    return True 

Để thêm tài liệu để nó, bạn cần phải viết một chuỗi multiline dưới đây định nghĩa của nó (được gọi trong thế giới Python docstring), như

này

def func(arg1, arg2): 
    """Summary line. 

    Extended description of function. 

    Parameters 
    ---------- 
    arg1 : int 
     Description of arg1 
    arg2 : str 
     Description of arg2 

    Returns 
    ------- 
    bool 
     Description of return value 

    Examples 
    -------- 
    >>> func(1, "a") 
    True 
    """ 
    return True 

Điều Spyder làm là lấy mô tả văn bản thuần túy này, phân tích cú pháp và hiển thị dưới dạng html và cuối cùng hiển thị nó trong Trình kiểm tra đối tượng.

Để xem nó, bạn chỉ cần gọi func ở một nơi khác trong mã của bạn và nhấn Ctrl + i bên cạnh nó, như thế này:

func<Ctrl+i>(1, "a") 

này cũng được hiển thị tự động khi bạn viết một dấu ngoặc đơn bên trái bên cạnh func.

Answer 2

Nếu bạn có dự án của bạn Python (hoặc file) đã ghi nhận với một phong cách khác (như reStructuredText hoặc Epytext) hay không thành văn bản, bạn có thể tạo/chuyển đổi docstrings vào NumpyDoc phong cách sử dụng Pyment:

pyment -o numpydoc /my/python/project 

Lưu ý rằng lệnh trước đó, chạy sau khi cài đặt Pyment, sẽ tạo ra các bản vá lỗi cần được áp dụng cho mã của bạn.

Khi dự án của bạn được ghi lại bằng cách sử dụng kiểu Numpydoc, bạn có thể sử dụng Sphinx extension để tạo tài liệu đẹp có thể đọc được của mình!