autosummary с toctree также выводит список импортированных членов

Я использую Sphinx и autosummary для создания документации программного обеспечения Python. Он работает хорошо, но в созданных файлах .rst также перечислены импортированные функции и классы, чего я бы не хотел.

Например, пакет packageex со строкой документации:

"""
Package Example (:mod:`packageex`)
==================================

.. currentmodule:: packageex
.. autosummary::
   :toctree:

   module0
   module1
"""

создаст файл packageex.module0.rst с

Module0 (:mod:`packageex.module0`)
=================================

.. currentmodule:: packageex.module0

.. rubric:: Functions

.. autosummary::

   f0
   f1
   f2_imported
   f3_imported

.. rubric:: Classes

.. autosummary::

   Class0
   ClassImported

Есть ли способ перечислить только функции и классы, определенные в модуле (а не импортированные)?

В документе autodoc (http://sphinx-doc.org/latest/ext/autodoc.html): «В директиве automdule с установленной опцией members будут задокументированы только те элементы модуля, атрибут __module__ которых равен имени модуля, заданному модулю automdule. Это необходимо для предотвращения документации импортированных классов или функции. Установите параметр import-members, если вы хотите предотвратить такое поведение и задокументировать все доступные элементы. Обратите внимание, что атрибуты из импортированных модулей не будут задокументированы, поскольку документация по атрибутам обнаруживается путем анализа исходного файла текущего модуля ». Можно ли добиться того же поведения с автосводкой?


python python-sphinx toctree
person paugier    schedule 20.08.2014    source источник
comment
См. bitbucket.org/birkenfeld/sphinx/issue/1061/ < / а>   -  person mzjn    schedule 20.08.2014

Ответы (1)


arrow_upward
5
arrow_downward

Как упоминал mzjn, это известное странное поведение автосуммирования расширений. Чтобы получить желаемое поведение (т.е. предотвратить перечисление импортированных объектов), я только что изменил функцию get_members (l. 166 из sphinx.ext.autosummary.generate) следующим образом:

def get_members(obj, typ, include_public=[], imported=False):
    items = []
    for name in dir(obj):
        try:
            obj_name = safe_getattr(obj, name)
            documenter = get_documenter(obj_name, obj)
        except AttributeError:
            continue
        if documenter.objtype == typ:
            try:
                cond = (
                    imported or 
                    obj_name.__module__ == obj.__name__
                    )
            except AttributeError:
                cond = True
            if cond:
                items.append(name)
    public = [x for x in items
              if x in include_public or not x.startswith('_')]
    return public, items
person paugier    schedule 23.08.2014
comment
заметил, что эта проблема все еще существует в последней версии сфинкса. не уверен, почему это не исправлено с помощью кода здесь. это очень прискорбно. - person RNA; 12.02.2016
comment
Это все еще проблема? github.com/sphinx-doc/sphinx/issues/1061 закрыт . - person mzjn; 14.03.2016
comment
На всякий случай: этот код у меня не работает. Файл .rst, созданный для документирования моего модуля, пуст. Используйте осторожно! - person Gerhard Hagerer; 19.10.2016