Often python extension modules define submodules like this:

static PyObject *
initfoo_xpto(void)
{
    PyObject *m;
    m = Py_InitModule3("foo.xpto", foo_xpto_functions, NULL);
    [...]
    return m;
}

PyMODINIT_FUNC
initfoo(void)
{
    PyObject *m;
    PyObject *submodule;
    m = Py_InitModule3("foo", foo_functions, NULL);
    [...]
    submodule = initfoo_xpto();
    Py_INCREF(submodule);
    PyModule_AddObject(m, "xpto", submodule);
}

Unfortunately pydoc does not list these submodules. Attached patch
fixes it.

This patch duplicates entries for "package contents" and "submodules";
this is not good. (E.g. for help(email):

NAME
email - A package for parsing, handling, and generating email messages.

FILE
/home/gbr/devel/python/Lib/email/init.py

PACKAGE CONTENTS
_parseaddr
base64mime
charset
encoders
errors
feedparser
generator
header
iterators
message
mime (package)
parser
quoprimime
test (package)
utils

SUBMODULES
_parseaddr
base64mime
charset
email
encoders
errors
feedparser
generator
header
iterators
message
mime
parser
quoprimime
sys
utils
)

This should be a better patch, although it only applies to the text
formatter of pydoc, not the HTML one (I'm too lazy for this :-)).

The patch only amends TextDoc -- what about HtmlDoc?

Actually, HtmlDoc already lists all module members in the inspected
module (regardless of whether they are modules imported from outside or
submodules defined inline). You can try it with the updated pydocfodder:

>>> import pydoc
>>> from test import pydocfodder
>>> pydoc.writedoc(pydocfodder)
wrote test.pydocfodder.html

... and check that test.pydocfodder.html contains a reference to
test.pydocfodder.submodule.

Well, I believe you. :)

Committed r60178.