Pydoc создает неполную документацию

Я создал свой первый пакет и заметил, что документация, которая появляется, когда пользователь звонит help(my_package) является неполным. Было бы неплохо, чтобы при вызове перечислялись классы, методы, функции и атрибуты. help(), И в идеале описание функций из docstrings.

Чтение pydoc Документация, я до сих пор не знаю, как это сделать, так как предоставленная информация немного скудна.

Когда я правильно понял, "вывод" для help() автоматически создается, когда пользователь вызывает эту функцию? Или я должен предоставить и указать что-то дополнительное?

В настоящее время это выглядит так, когда я звоню help() на моем пакете (здесь: pdbsr):

Help on package pdbsr:

NAME
    pdbsr

FILE
    /.../pdbsr/__init__.py

PACKAGE CONTENTS
    bugtest (package)
    exceptions (package)
    extras (package)
    info (package)
    pdbfile (package)

SUBMODULES
    pdb_properties
    slide

DATA
    __version__ = '0.1.0'
    l2lvl = ['HEADER    LANTIBIOTIC-BINDING-PROTEIN             06-JUL-12 ...
    l3eiy = ['HEADER    HYDROLASE                               17-SEP-08 ...
    s2lvl = 'HEADER    LANTIBIOTIC-BINDING-PROTEIN           ...    0    0...
    s3eiy = 'HEADER    HYDROLASE                             ...    0   13...

VERSION
    0.1.0

И когда я вызываю подмодули, например, pdbsr.exceptions:

Help on package pdbsr.exceptions in pdbsr:

NAME
    pdbsr.exceptions

FILE
    /.../pdbsr/exceptions/__init__.py

PACKAGE CONTENTS
    pdb_exceptions

(END)

Вот краткий обзор моей текущей структуры папок:

И мой установочный файл в настоящее время выглядит так:

try:
    from setuptools import setup
except ImportError:
    from distutils.core import setup



setup(
      name='pdbsr',
      version='0.1.0',
      description='Protein Structure File Utilities',
      long_description=open('README.rst').read() + '\n\n' +
                       open('HISTORY.rst').read(),
      author='Sebastian Raschka',
      author_email='...',
      license=open('LICENSE').read(),
      #url='...',
      packages = [
         'pdbsr',
         'pdbsr.bugtest', 
         'pdbsr.exceptions', 
         'pdbsr.pdbfile',
         'pdbsr.extras',
         'pdbsr.info'
      ],
      package_dir={'pdbsr': 'pdbsr'},
      package_data={'': ['LICENCE']},
      install_requires=[''],
      include_package_data=True,
      )

И это содержание моего высшего __init__.py файл:

from info.version import __version__

from pdbfile.new_pdb import *
from pdbfile.load_pdb import *
from pdbfile.pdb_lig import *
from pdbfile.pdb_prot import *

from bugtest.doct_2lvl import *
from bugtest.doct_3eiy import *

import extras.slide_functions as slide
Источник

2 ответа

Решение

Каждый из ваших классов и функций, как внутри, так и за пределами классов, должен иметь строку кода * в коде *, как показано ниже, тогда help поможет сделать его волшебным:

class SomeClass():
   """ Documentation at a high level about the class """

   def ClassMethod():
      """ Documentation about class method """
      # Actual Code

Скопировано из комментариев:

дело в том, что все мои классы и методы уже имеют строки документации, как вы описали. Например, когда я вызываю справку (pdbsr.NewPdb), у этого класса все нормально, но класс не отображается в общей справке (pdbsr) - это то, что беспокоит меня - Себастьян Рашка

Вы пытались использовать __all__ = ["package_item", ] в файлах __init__.py, а не из???? импорт * заявления?

да, я попробовал это сначала и действительно не мог заставить это работать со всеми = [...] - я не знаю почему. Моя цель заключается в том, чтобы все классы и функции были доступны, например, pdbsr.function() без использования более чем 1-точечной записи для подпакетов. Как бы вы сделали это, учитывая все мои структуры папок? Я также пытался использовать all в файлах __init__ подпакетов, но по какой-то причине не смог заставить его работать:(

Я думаю - при просмотре справочной информации вам нужно иметь в каждом из подмодулей __init__.py и '__all__ = [...]', где... заменяется запятым списком имен в кавычках того, что он включает из этого модуля в случае "импорта из модуля *" - когда я впервые начал использовать модули, я пропустил, что это был список имен, а не список объектов.

Источник

Проблема в том, что сначала нужно запустить pydoc на модуле, а затем каждый py-файл внутри модуля. Я использую Windows, поэтому я добавил SET PYTHONPATH=C:/Python27 в файл CMD. bde- мой пакет, помещенный в site-packages, и внутри него есть несколько скриптов.

%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde

Когда вы запустите pydoc для имени модуля, вы получите.html в вашем текущем каталоге, который содержит сводку из файла init.py и ссылки на все включенные файлы. Но им нужна цель, чтобы ссылки работали.

Так что просто запустите pydoc снова для каждого подмодуля:

%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.auto_model 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.settings 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.static 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.validate_csv
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.model 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.mixin 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.create_table 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.make_model 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.apply 
%PYTHONPATH%/python %PYTHONPATH%\lib\pydoc.py -w bde.copy_data

Тогда у вас будет полное HTML-дерево со всеми ссылками на файлы. И так далее, если у вас есть sub-sub модули. Если у вас есть некоторые встроенные модули, такие как sys, они не будут связываться, но вы также можете запустить pydoc на них.

Источник
Другие вопросы по тегам