1

我创建了我的第一个包，我注意到用户调用时显示的文档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
4

2 回答 2

1

问题实际上是 pydoc 必须首先在模块上运行，然后是模块中的每个 py 文件。我正在使用 Windows，所以我将 SET PYTHONPATH=C:/Python27 添加到 CMD 文件中。bde 是我放入站点包的包，里面有许多脚本。

%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。

于 2014-11-28T08:27:09.100 回答
0

您的每个类和函数，无论是在类中还是类之外，都需要在代码中包含一个文档字符串 *，如下所示，那么 help 会很神奇：

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

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

复制自评论：

问题是我所有的类和方法都已经有了你描述的文档字符串。例如，当我调用 help(pdbsr.NewPdb) 时，这个类的一切都很好，但是这个类没有出现在一般的 help(pdbsr) 中——这让我很困扰——Sebastian Raschka

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

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

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

于 2013-07-22T19:19:22.137 回答