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

Question

I am trying to generate documentation for my python project with pdoc module by following this article .

I noticed that all the classes, methods, etc starting with __ (private/protected ones) are missing in the generated documentation.

This is the sample.py

class __Members:
    def __test():
        pass

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

This is how I generated the documentation with pdoc

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

I see only public class in the generated documentation as per this screenshot:

Can someone please help me figure out a way to get over this limitation and generate the documentation with all the private/protected members? Thanks in advance.

Answer 1

Pdoc only extracts public API members (not prefixed with an underscore) by convention.

You may be able to override this behavior, on a module level, by defining __all__ , or, more generally, by specifying overrides in the __pdoc__ dict , either manually for a few members, or automatically yet hackish, somewhat like:

# 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__'}})

Alternatively, you should just rename your members if they are part of your public API.

Also note, Python by default defines dozens of dunder members on objects, most of which have standard meaning or are internal:

>>> 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__']