Наследование Docstring для свойств, использующих автодок sphinx

Question

У меня есть такой класс:

class MyBase(object):
   x = 3
   """Documentation for property x"""

и другой класс, который его наследует:

class MyObj(MyBase):
   x = 0

Когда я использую автодок sphinx для создания документации, MyObj.x не документируется,Есть ли способ унаследовать строку документации от MyBase.x?Я нашел DocInherit , но, поскольку он использует декоратор, он работает только для методов класса.Любой способ сделать это со свойствами?

Answer 1

Я нашел обходной путь, используя функцию свойства:

class MyBase(object):
   _x = 3
   x = property( lambda s: s._x, doc="Documentation for property x")

class MyObj(MyBase):
   _x = 0

Это хорошо, учитывая переменную экземпляра:

>>> m = MyObj()
>>> m.x
0

можно вызвать help(m) и получить надлежащую документациюсвойства x, и сфинкс также правильно его подхватывает.

Answer 2

Насколько я знаю, строки документации для атрибутов не являются частью Python. Когда я пытаюсь это сделать, MyBase.x.__doc__ не получает строку под ним. Строки документов работают только с классами, функциями и методами. Если Sphinx выбирает строку под x = 3 как строку документации, он, вероятно, выполняет собственную обработку исходного кода, чтобы получить это.

Answer 3

Если вы заботитесь только о создании документации через Sphinx. ты можешь использовать: ": Наследственные-члены:"

.. autoclass:: Noodle
   :members:
   :inherited-members:

Это также добавит строки документации унаследованных членов в документацию Sphinx.

http://sphinx -doc.org / внутр / autodoc.html

Answer 4

Как уже сказал Томас, атрибуты не имеют строк документации в Python.Однако Sphinx обеспечивает собственную обработку, позволяющую задокументировать атрибуты.

class Test(object):
    #: This is an attibute docstring.
    test_attr = 'test'

    @property
    def test_prop(self):
        """This is a property docstring."""

В результате:

class Test
    Bases: object

    test_attr = 'test'
        This is an attibute docstring.

    test_prop
        This is a property docstring.