Python: как встроить всю справочную документацию в меню справки на уровне пакета? - PullRequest
Новая
       49

Python: как встроить всю справочную документацию в меню справки на уровне пакета?

6 голосов
/ 20 марта 2019

Я хочу спросить:

  • TLDR: как мне получить помощь моего пакета, чтобы включить все базовые строки документации?
  • Я создал пакет,Этот пакет имеет все надлежащие файлы __init__.py и все соответствующие строки документов (строки документов уровня модуля, функции, класса и метода).Тем не менее, когда я выполняю help(mypackage), единственная предоставляемая помощь - это помощь, предоставляемая на этом модуле __init__.py верхнего уровня.

Часто на уровне пакета справка включает не всеиз базовых строк документов, но иногда это делает .

Я хочу убедиться, что я встраиваю все базовые строки документов.

Например, вnumpy пакет все базовые строки документации доступны в справке в командной строке, даже если они не предоставлены на верхнем уровне __init__.py.

Т.е. я могу набрать

>>> help(numpy)

и ознакомьтесь со всей документацией, включая документацию, определенную вне модуля инициализации dunder.

Однако многие другие пакеты, в том числе популярные, такие как pandas не перехватывает всю основную документацию.

Т.е., набрав 

>>> help(pandas)

, я получаю только документацию, определенную в __init__.py.

Я хочу создать документацию на уровне пакетазеркальное отражение того, как numpy делает это.

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

1 Ответ

6 голосов
/ 27 марта 2019

numpy показывает документацию по классам и функциям, определенным вне модуля __init__.py из-за добавления их имен в переменную __all__ в __init__.py.Попробуйте комментировать строки 169-173 (не забудьте раскомментировать!): 

#__all__.extend(['__version__', 'show_config'])
#__all__.extend(core.__all__)
#__all__.extend(_mat.__all__)
#__all__.extend(lib.__all__)
#__all__.extend(['linalg', 'fft', 'random', 'ctypeslib', 'ma'])

После выполнения этого вывода help(numpy) будет очень ограниченным.

Также давайте воспроизведем это поведение,Начиная с '/some/path', создайте внутри нее папку folder, файл с именем file.py со следующим содержимым: 

class Class:
    """Class docstring"""

и __init__.py: 

from .file import *

Теперь посмотримсправка: 

/some/path$ python3.5
>>> import folder
>>> help(folder)

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

FILE
    /some/path/folder/__init__.py

А теперь добавьте эту строку в __init__.py: 

__all__ = ['Class']

После повторного импорта folder команда help(folder) будет содержать информацию о class Class, которая включает в себяВаша документация: 

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

CLASSES
    builtins.object
        folder.file.Class

    class Class(builtins.object)
     |  Class docstring
     |  
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

DATA
    __all__ = ['Class']

FILE
    /some/path/folder/__init__.py
...