Могу ли я переопределить строку документации для определенного свойства класса в автодоке Sphinx? - PullRequest
Новая
       84

Могу ли я переопределить строку документации для определенного свойства класса в автодоке Sphinx?

0 голосов
/ 11 октября 2019

Использование Sphinx 2.2.0 и python 3.6.8

У меня есть два класса, A и B, а свойство A создает экземпляр B. Я хотел бы, чтобы мой вывод sphinx html ссылался на объект B, но я бы хотел, чтобы необработанная строка документации не имела форматирования sphinx / rest. Я использую autodoc, и большинство методов и свойств в A не требуют этой модификации, но я хотел бы сделать это в нескольких местах, если это возможно. 

class A(object):
    """
    This is class A.
    """
    @property
    def getB(self):
        """
        Get an instance of B.
        """
        return B()

    # A also includes many other methods and properties which 
    # I want to document using autodoc

class B(object):
    pass

Я могу написать Get an instance of :class:`<B>`. в getB строке документа, но тогда A.getB.__doc__ или help(A.getB) содержат этот точный текст. Я хотел бы, чтобы A.getB.__doc__ оставался Get an instance of B, но имел ссылку в выводе html, сгенерированном autodoc. 

class A  
Bases: object  

    getB  
        Get an instance of B̲.

Предполагая, что A находится в a.py, я попытался 

.. automodule:: a
   :member: A
   :exclude-member: getB

   .. method:: getB
      :property:

      get an instance of :class:`<B>`.

Однако это не помещает B в документацию класса A или правильно ссылается на класс B. 

property a.getB
Get an instance of B.

class A
Bases: object

Я также пробовал .. method:: a.getB и .. method:: a.A.getB, но безуспешно.

Если не попытаться получить вывод autodoc и изменить его напрямую, есть ли способ сделать это?

1 Ответ

1 голос
/ 13 октября 2019

Чтобы поместить вывод из .. method:: getB в документацию класса A, вам нужно использовать autoclass вместо automodule. 

.. autoclass:: a.A
   :members:
   :exclude-members: getB

   .. method:: getB
      :property:

      Get an instance of :class:`B`.
...