pydoc 创建不完整的文档

Question

我创建了我的第一个包，我注意到当用户调用 help(my_package) 时显示的文档不完整。我会很高兴在调用help() 时列出类、方法、函数和属性。理想情况下，来自docstrings 的功能描述。

阅读pydoc 文档，我仍然不知道该怎么做，因为那里提供的信息有点稀疏。

当我理解正确时，help() 的“输出”是在用户调用此函数时自动创建的？还是我必须提供并指定一些额外的东西？

目前，当我在我的包（这里：pdbsr）上调用help() 时，它看起来像这样：

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。

Answer 2

您的每个类和函数，无论是在类内还是类外，都需要在代码中包含一个文档字符串 **，如下所示，那么 help 就会发挥作用：

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

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

复制自评论：

问题是我所有的类和方法都已经有了 如您所描述的文档字符串。例如，当我调用 help(pdbsr.NewPdb) 这门课一切都很好，但该课没有出现在 一般帮助（pdbsr） - 这就是困扰我的问题 – Sebastian Raschka

您是否尝试过在 __init__.py 文件中使用 __all__ = ["package_item", ] 而不是来自 ？？？导入 * 语句？

是的，我首先尝试过，但真的无法让它与 all = [...] 一起使用 - 我没有 知道为什么。我的目标是所有的类和函数都应该是 可用例如 pdbsr.function() 不使用超过 1 个点 子包的符号。你会怎么做 考虑我的文件夹结构？我也尝试在 __init__ 子包的文件，但由于某种原因我无法让它工作:(

我认为-从查看帮助开始，您需要在每个子模块 __init__.py 中添加一个 '__all__ = [...]' ... 替换为逗号分隔的引用名称列表 在“从模块导入 *”的情况下包含该模块 - 当我第一次开始使用模块时，我错过了它是一个列表 名称不是对象列表。