Làm cách nào để sử dụng autodoc của Sphinx để ghi lại phương thức __init __ (self) của một lớp?

Sphinx không tạo tài liệu cho __init __ (self) theo mặc định. Tôi đã thử những cách sau:

.. automodule:: mymodule
    :members:

và

..autoclass:: MyClass
    :members:

Trong conf.py, cài đặt sau chỉ nối chuỗi doc_init __ (self) vào chuỗi docstring của lớp ( tài liệu tự động mã Sphinx dường như đồng ý rằng đây là hành vi mong đợi, nhưng không đề cập gì đến vấn đề tôi đang cố gắng giải quyết):

autoclass_content = 'both'

Dưới đây là ba lựa chọn thay thế:

1. Để đảm bảo điều đó __init__()luôn được ghi lại, bạn có thể sử dụng autodoc-skip-membertrong conf.py. Như thế này:

   def skip(app, what, name, obj, would_skip, options):
       if name == "__init__":
           return False
       return would_skip
   
   def setup(app):
       app.connect("autodoc-skip-member", skip)

   Điều này xác định rõ ràng __init__không được bỏ qua (theo mặc định). Cấu hình này được chỉ định một lần và nó không yêu cầu bất kỳ đánh dấu bổ sung nào cho mọi lớp trong nguồn .rst.

2. Các special-memberstùy chọn được thêm vào trong Sphinx 1.1 . Nó làm cho các thành viên "đặc biệt" (những người có tên như__special__ ) được ghi lại bằng autodoc.

   Kể từ Sphinx 1.2, tùy chọn này nhận các đối số làm cho nó hữu ích hơn so với trước đây.

3. Sử dụng automethod:

   .. autoclass:: MyClass     
      :members: 
   
      .. automethod:: __init__

   Điều này phải được thêm vào cho mọi lớp (không thể được sử dụng với automodule, như đã chỉ ra trong nhận xét cho bản sửa đổi đầu tiên của câu trả lời này).

Bạn đã gần. Bạn có thể sử dụng autoclass_contenttùy chọn trong conf.pytệp của mình :

autoclass_content = 'both'

Trong những năm qua, tôi đã viết một số biến thể của lệnh autodoc-skip-membergọi lại cho các dự án Python không liên quan khác nhau vì tôi muốn các phương thức như __init__(), __enter__()và__exit__() để hiển thị trong tài liệu API của tôi (sau khi tất cả, những "phương pháp đặc biệt" là một phần của API và những gì nơi tốt hơn để ghi lại chúng hơn bên trong docstring của phương thức đặc biệt).

Gần đây, tôi đã thực hiện tốt nhất và biến nó thành một trong những dự án Python của tôi ( đây là tài liệu ). Việc triển khai về cơ bản là:

import types

def setup(app):
    """Enable Sphinx customizations."""
    enable_special_methods(app)


def enable_special_methods(app):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    :param app: The Sphinx application object.

    This function connects the :func:`special_methods_callback()` function to
    ``autodoc-skip-member`` events.

    .. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
    """
    app.connect('autodoc-skip-member', special_methods_callback)


def special_methods_callback(app, what, name, obj, skip, options):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    Refer to :func:`enable_special_methods()` to enable the use of this
    function (you probably don't want to call
    :func:`special_methods_callback()` directly).

    This function implements a callback for ``autodoc-skip-member`` events to
    include documented "special methods" (method names with two leading and two
    trailing underscores) in your documentation. The result is similar to the
    use of the ``special-members`` flag with one big difference: Special
    methods are included but other types of members are ignored. This means
    that attributes like ``__weakref__`` will always be ignored (this was my
    main annoyance with the ``special-members`` flag).

    The parameters expected by this function are those defined for Sphinx event
    callback functions (i.e. I'm not going to document them here :-).
    """
    if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
        return False
    else:
        return skip

Có, có nhiều tài liệu hơn logic :-). Ưu điểm của việc xác định một lệnh autodoc-skip-membergọi lại như thế này so với việc sử dụng special-memberstùy chọn (đối với tôi) là special-memberstùy chọn này cũng cho phép tạo tài liệu về các thuộc tính như __weakref__(có sẵn trên tất cả các lớp kiểu mới, AFAIK) mà tôi cho là nhiễu và không hữu ích chút nào. Phương pháp gọi lại tránh điều này (vì nó chỉ hoạt động trên các hàm / phương thức và bỏ qua các thuộc tính khác).

Mặc dù đây là một bài đăng cũ hơn, nhưng đối với những người đang tìm kiếm nó, cũng có một giải pháp khác được giới thiệu trong phiên bản 1.8. Theo tài liệu , Bạn có thể thêm special-memberkhóa trong autodoc_default_options vàoconf.py .

Thí dụ:

autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Đây là một biến thể chỉ bao gồm __init__nếu nó có các đối số:

import inspect

def skip_init_without_args(app, what, name, obj, would_skip, options):
    if name == '__init__':
        func = getattr(obj, '__init__')
        spec = inspect.getfullargspec(func)
        return not spec.args and not spec.varargs and not spec.varkw and not spec.kwonlyargs
    return would_skip

def setup(app):
    app.connect("autodoc-skip-member", skip_init_without_args)