Должен ли Sphinx документировать атрибуты экземпляра в классе? - PullRequest
Новая
       26

Должен ли Sphinx документировать атрибуты экземпляра в классе?

1 голос
/ 21 июня 2019

Я нахожу противоречивую и часто устаревшую информацию, поэтому надеюсь, что кто-то сможет это выяснить.

Я бы хотел документировать что-то подобное, используя Sphinx: 

class MyClass:
    """
    MyClass, which is documented with a docstring at the class level
    """
    classVar = None
    """A class var with an initial value and a 1-line doc"""

    def __init__(self):
        """
        __init__'s docs
        """
        instanceVar1 = 10
        """An instance var with an initial val and 1-line doc"""

        #: An instance var with an initial val and a doc-comment
        instanceVar2 = 10

В моих документахЯ хотел бы видеть instanceVar1 и его строку документации (в идеале с его значением по умолчанию, но я был бы рад только описанием).Но если я запускаю с первым файлом: 

.. automodule:: mymodule.mycode
   :members:

, я вижу только атрибуты класса, а не атрибуты экземпляра: Image showing docs

Поиск в Google приводит к конфликтуинформация о том, что должно / не должно работать.Несколько старых цепочек переполнения стека указывают на проблемы с автодокументацией для атрибутов экземпляра (например, здесь ), но они также ссылаются на это, если вы добавили строки документации, как я делал выше.Документы Sphinx указывают, что все атрибуты могут быть автоматически документированы .

Кто-нибудь может прокомментировать, должно ли то, что я пытаюсь сделать, сработало / теперь это работает для вас, вы / предложения о том, что я, возможно, испортил?Благодаря.

1 Ответ

0 голосов
/ 21 июня 2019

Да, то, что вы сделали , должно работать, и это - в конце концов - сработало для меня.

Чтобы продемонстрировать, я использую пример из документации Сфинкса, который вы привели: 

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

Я сохранил это как module.py и создал следующее index.rst: 

.. automodule:: module

Вместе с этим файлом конфигурации Sphinx, conf.py: 

import sys
sys.path.insert(0, '.')
extensions = ['sphinx.ext.autodoc']
autodoc_default_options = {
    'members':         True,
    'member-order':    'bysource',
    'special-members': '__init__',
}

Со всеми тремя файлами, хранящимися в одной папке, я запустил Sphinx (2.1.1) через sphinx-build . ./html (на Python 3.7.3 и Windows 10), чтобы отобразить его как HTML: rendered HTML

Что касается того, что вы "могли испортить" ... Хм, это правильно, как я уверен, вы согласитесь. ;-) Мне потребовалось много времени, чтобы понять это, когда я сначала попробовал то же самое, что и выше, но с примером кода, который вы предоставили: два ваших предполагаемых атрибута экземпляра, instanceVar1 и instanceVar2, пропускают self идентификатор впереди. К сожалению. Вот почему это не сработало.

...