pdoc3 0.3.12

Special docstring conventions used by pdoc

Firstly, docstrings can be inherited. Consider the following code sample:

#!python
>>> class A (object):
...     def test():
...         '''Docstring for A.'''
...
>>> class B (A):
...     def test():
...         pass
...
>>> print(A.test.__doc__)
Docstring for A.
>>> print(B.test.__doc__)
None

In Python, the docstring for B.test is empty, even though one was defined in A.test. If pdoc generates documentation for the above code, then it will automatically attach the docstring for A.test to B.test only if B.test does not have a docstring. In the default HTML output, an inherited docstring is grey.

Secondly, docstrings can be attached to variables, which includes module (or global) variables, class variables and instance variables. Python by itself does not allow docstrings to be attached to variables. For example:

#!python
variable = "SomeValue"
'''Docstring for variable.'''

The resulting variable will have no __doc__ attribute. To compensate, pdoc will read the source code when it’s available to infer a connection between a variable and a docstring. The connection is only made when an assignment statement is followed by a docstring.

Something similar is done for instance variables as well. By convention, instance variables are initialized in a class’s __init__ method. Therefore, pdoc adheres to that convention and looks for docstrings of variables like so:

#!python
def __init__(self):
    self.variable = "SomeValue"
    '''Docstring for instance variable.'''

Note that pdoc only considers attributes defined on self as instance variables.

Class and instance variables can also have inherited docstrings.

Thirdly and finally, docstrings can be overridden with a special __pdoc__ dictionary that pdoc inspects if it exists. The keys of __pdoc__ should be identifiers within the scope of the module. (In the case of an instance variable self.variable for class A, its module identifier would be A.variable.) The values of __pdoc__ should be docstrings.

This particular feature is useful when there’s no feasible way of attaching a docstring to something. A good example of this is a namedtuple:

#!python
__pdoc__ = {}

Table = namedtuple('Table', ['types', 'names', 'rows'])
__pdoc__['Table.types'] = 'Types for each column in the table.'
__pdoc__['Table.names'] = 'The names of each column in the table.'
__pdoc__['Table.rows'] = 'Lists corresponding to each row in the table.'

pdoc will then show Table as a class with documentation for the types, names and rows members.

Note that assignments to __pdoc__ need to placed where they’ll be executed when the module is imported. For example, at the top level of a module or in the definition of a class.

If __pdoc__[key] = None, then key will not be included in the public interface of the module.