如何使用pdoc生成包含私有/受保护类python项目文档

Question

我正在尝试通过这个article为我的带有pdoc模块的python项目生成文档。

我注意到生成的文档中缺少所有以__ (私有/受保护的)开头的类、方法等。

这是sample.py

class __Members:
    def __test():
        pass

class seedoc:
    ''' see me '''
    pass

这就是我用pdoc生成文档的方式。

$pdoc --html sample.py
html/sample.html

根据此屏幕截图，我在生成的文档中仅看到公共类：

​

有没有人能帮我想个办法克服这个限制，生成包含所有私有/受保护成员的文档？提前谢谢。

Answer 1

按照惯例，仅extracts public API members (不带下划线前缀)。

您可以在模块级别上通过定义__all__来覆盖此行为，或者更一般地，通过在__pdoc__ dict中指定覆盖，可以手动为几个成员指定覆盖，也可以通过自动但不太复杂的方式进行覆盖，有点像：

# Specified at the end of each module that contains private
# classes/methods that need to be exposed
__pdoc__ = {name: True
            for name, klass in globals().items()
            if name.startswith('_') and isinstance(klass, type)}
__pdoc__.update({f'{name}.{member}': True
                 for name, klass in globals().items()
                 if isinstance(klass, type)
                 for member in klass.__dict__.keys()
                 if member not in {'__module__', '__dict__', 
                                   '__weakref__', '__doc__'}})

或者，如果您的成员是您的公共API的一部分，那么您应该只重命名这些成员。

还请注意，Python默认情况下在对象上定义dozens of dunder members，其中大多数具有标准含义或内部含义：

>>> class Cls:
...     pass

>>> dir(Cls)
['__class__',
 '__delattr__',
 '__dict__',
 '__dir__',
 '__doc__',
 '__eq__',
 '__format__',
 '__ge__',
 '__getattribute__',
 '__gt__',
 '__hash__',
 '__init__',
 '__init_subclass__',
 '__le__',
 '__lt__',
 '__module__',
 '__ne__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__setattr__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 '__weakref__']