Is there a way to generate pydoc for nested functions? [closed]

Question

I'm looking for a way to generate documentation, pydoc on this case, for nested functions. Is this possible with pydoc? Is it possible with other tools?

For example:

"""
Module docstring.
"""

def foo(x):
    """
    Foo does something.
    """
    ...

    def bar(y):
        """
        Bar does something
        """
        ...

Generating pydoc with: pydoc -w -filename- will generate pydoc for the module and foo() but not for bar().

Normally this would be ok; the problem is that I'm trying to build a library for educational purposes, and documenting what happens inside the closure is specially helpful. I want to find a way to document it without having to expose the inner functions to the global scope.

Answer 1

There is always the manual method:

"""
Module docstring.
"""

def foo(x):
    """
    Foo does something.
    N.B. Foo includes a local function bar() that does what bar does.
    """
    ...

    def bar(y):
        """
        Bar does something
        """
        ...

It is not automatic but it does mean that your students only get to see documentation on those private methods that you wish them to see.