Наследование строк документации для свойств с использованием autodoc от sphinx

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

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

и еще один класс, наследующий его:

class MyObj(MyBase):
   x = 0

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


python python-sphinx autodoc
person jterrace    schedule 01.04.2011    source источник
comment
Не пытаюсь переубедить вас, но ... у вашего документа есть дерево наследования. Почему бы пользователю MyObj просто не щелкнуть ссылку, чтобы перейти к родительскому объекту, а затем просмотреть там документацию по родительскому объекту?   -  person Ross Rogers    schedule 02.04.2011
comment
Это возможно, но я думаю, что гораздо лучше иметь все методы и атрибуты класса (включая унаследованные) на одной странице, вместо того, чтобы просматривать его иерархию типов.   -  person jterrace    schedule 02.04.2011

Ответы (4)


arrow_upward
5
arrow_downward

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

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, и sphinx также правильно это поймет.

person jterrace    schedule 01.04.2011

arrow_upward
4
arrow_downward

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

person Thomas K    schedule 01.04.2011
comment
Это привело меня к мысли, что я должен использовать property() с параметром doc. Смотрите мой ответ. Это некрасиво, но я думаю, что это, вероятно, лучший способ сделать это, если у вас нет лучших предложений. - person jterrace; 01.04.2011
comment
@jterrace: я, конечно, не очень хочу превращать x в свойство с геттером только для того, чтобы добавить строку документации. Я не думаю, что есть другой способ сделать это, но я обычно оставляю атрибуты без строки документации или описываю важные в строке документации класса. - person Thomas K; 02.04.2011
comment
@ Thomas-K: Я согласен, но альтернативой является дублирование строки документации, что делает поддержку документации довольно утомительной. - person jterrace; 02.04.2011

arrow_upward
3
arrow_downward

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

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

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

http://sphinx-doc.org/ext/autodoc.html

person stephan schultchen    schedule 17.03.2015

arrow_upward
1
arrow_downward

Как уже сказал Томас, атрибуты не имеют строк документации в 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.
person siebz0r    schedule 30.12.2013