python - pydoc 创建不完整的文档

Question

我创建了第一个包，我注意到用户调用 help(my_package) 时显示的文档不完整。我很乐意在调用 help() 时获取列出的类、方法、函数和属性。最好是来自 docstring 的函数描述。

阅读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

Answer 1

问题实际上是 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 树，其中包含引用的所有文件。如果您有子子模块，依此类推。如果您有一些内置模块(例如 sys)，它们将不会链接，但您也可以在它们上运行 pydoc。