Question

我创建了我的第一个包，我注意到用户调用help(my_package)时显示的文档不完整。调用help()时，我会很高兴获得列出的类，方法，函数和属性。理想情况下，docstring s。

中的函数描述

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

以下是我当前文件夹结构的概述：

enter image description here

我的设置文件目前看起来像这样：

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

每个类和函数（包括类内外）都需要在代码 *中有一个docstring * ，如下所示，然后帮助将实现它的魔力：

class SomeClass(): """ Documentation at a high level about the class """ def ClassMethod(): """ Documentation about class method """ # Actual Code


从评论中复制：

问题是我的所有类和方法都已经存在   你描述的docstrings。例如，当我打电话求助时（pdbsr.NewPdb）   这个课程的一切都很好，但课程没有出现   一般的帮助（pdbsr） - 这让我感到困扰 - 塞巴斯蒂安拉施卡

您是否尝试在__init__.py文件中使用__all__ = [“package_item”，]而不是   ???? import * statements？

是的，我先尝试过，真的无法让它与所有人一起工作= [...] - 我没有   知道为什么。我的目标是所有的类和功能都应该是   可用作例如pdbsr.function（）而不使用多于1个点   子包的表示法。你会怎么做到这一点   考虑我的文件夹结构？我也试过用一个全部   __init__子包的文件，但由于某种原因我无法让它工作:(

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

pydoc创建不完整的文档

2 个答案:

从评论中复制：