Làm cách nào để tạo tài liệu cho trình thiết lập thuộc tính Python bằng Sphinx?

Question

Tôi có một cái gì đó lớp Python như sau, với docstrings dự định sẽ được chuyển đổi thành tài liệu bằng cách Sphinx:

class Direction(object): 
    """ 
    A direction in which movement can be made. 
    """ 
    def __init__(self): 
     self._name = None 

    @property 
    def name(self): 
     """ 
     The unique name of the direction. 

     :return: The direction name 
     :rtype: string 
     """ 
     return self._name 

    @name.setter 
    def name(self, value): 
     """ 
     Sets the direction name. 

     :param string value: The direction name 
     """ 
     self._name = value 

Sản lượng Sphinx trông giống như sau:

lớpDirection (name) Một hướng mà trong đó chuyển động có thể được thực hiện.

tên Tên độc đáo của hướng.

Returns: Tên hướng

loại Return: chuỗi

đó là tốt như xa như nó đi, nhưng lưu ý sự vắng mặt hoàn toàn của bất kỳ thông tin về thiết lập name.

Có cách nào để đưa Sphinx tạo tài liệu cho trình thiết lập thuộc tính không?

Answer 1

Nhân sư bỏ qua tài liệu về các nhà định cư bất động sản để tất cả tài liệu cho thuộc tính phải ở phương thức @property.

Trong khi Nhân sư hiểu một số thẻ cụ thể (ví dụ: :param ...:), thẻ sẽ chấp nhận bất kỳ thẻ tùy chỉnh nào và sẽ hiển thị chúng dưới dạng nhãn cho văn bản đi theo chúng.

Do đó, một số nội dung như sau sẽ hiển thị tài liệu theo cách hợp lý (getter, setter và type có thể được thay đổi thành văn bản khác nếu cần).

@property 
def name(self): 
    """ 
    The unique name of the direction. 

    :getter: Returns this direction's name 
    :setter: Sets this direction's name 
    :type: string 
    """ 
    return self._name 

Các tài liệu được tạo ra trông giống như sau:

lớpDirection (tên) Một hướng trong đó phong trào có thể được thực hiện.

tên Tên độc đáo của hướng.

Getter: Returns tên của hướng này

Setter: Sets tên của hướng này

Loại: chuỗi

T để @BrenBarm và @ A-B-B chỉ cho tôi theo hướng của giải pháp này.