How to represent packages ?

[tristanlatr]

Hello,

It seems that the _MemberType variable is assigned to the following:

_MemberType = te.Annotated[
  t.Union[Data, Function, Class],
  A.unionclass({ 'data': Data, 'function': Function, 'class': Class }, style=A.unionclass.Style.flat)]

I was wondering if the _MemberType should be assign to the following instead:

_MemberType = te.Annotated[
  t.Union[Data, Function, Class],
  A.unionclass({ 'data': Data, 'function': Function, 'class': Class,  'module': Module }, style=A.unionclass.Style.flat)]

This way, modules will be able to contain other modules!

Tell me what you think,

Thanks

[NiklasRosenstein]

Hey @tristanlatr , funny you should mention this! I've been having this in the back of my mind (in addition to a few other things that should make traversing the API tree easier). And it actually came up as well yesterday on a Pydoc-Markdown PR discussion 😄

I'd prefer to introduce a new _ModuleMemberType which can include Module objects (and you need to also include Module in the t.Union[...]), as otherwise classes could contain modules.

Doing this should be mostly backwards-compatible, but docspec-python would need to be updated to return the modules nested instead of flat. This would probably need to be an option that is disabled by default (or a function to be applied after you have a list of modules) . I'm not sure yet how Pydoc-Markdown renderers would behave with nested modules, but most likely it won't work as expected right now.