Export title and description as module docstring

I see that since 2.2 you can export a module docstring via __doc__:

Also, the _md2dict function in the frontmatter module extracts a title and description from an h1 formatted markdown cell.

What does everyone think about having an option to export this title and description into the module docstring as an alternative to setting __doc__?

Some reasons why this might be good:

  • Having a __doc__ = in your notebook is a bit ugly and does not allow nice rendering.
  • If we have a #h1 and > description, then having a __doc__ as well might lead to duplicate content

One issue is that (AFAICT) the _md2dict function only extracts a single line as a description. In order to have multiline docstrings, this would need to be edited to allow multiline descriptions. So for example,:

# module title

> some description
> more description

the above would become the module level docstring (perhaps via some directive if appropriate).

Would be interested to hear the community’s thoughts. If there is interest and agreement I’d be happy to write a pull request.

Sounds like a great idea to me!