Display multiline docstrings

[gsganden]

I have a class with a docstring that looks like this:

class _Inspector:
    """Model inspector base class

    Users should use `get_inspector` to generate appropriate
    `_Inspector` objects rather than instantiating this class or its
    subclasses directly.
    """

I would like to display that docstring on my documentation site as it appears there, but neither of the provided renderers does the job. The default BasicMarkdownRenderer takes only the first line, so it removes the note about using get_inspector:

BasicHtmlRenderer shows the note, but without the line breaks separating the text blocks (and without the docment table):

I understand that I can plug in my own renderer, and I suspect that at least some of this behavior is the result of deliberate choices. I am wondering if you would want to either (1) change any of the behavior of the provided renderers or (2) provide additional renderers in the library. For instance, it might be helpful to provide renderers that display traditional NumPy- or Google-style docstrings in full for the sake of showing third-party library docs even if you want to encourage more succinct docs by default. I'd be happy to submit a PR if we can align on requirements.

[jph00]

@gsganden many thanks for the thoughtfully-presented and well-researched issue. Frankly, this decision goes back (IIRC) to the earliest days of nbdoc, the module that proceeded nbdev. At that stage, this whole approach was an early research idea and I was wondering how best to bring code into notebooks. Pretty much none of the code I was working with was designed to render nicely in notebooks, so I figured just keeping the first line of the docstring seemed like a reasonable compromise -- and then add prose in the notebook to explain any extra details.

Nowadays we have stuff like docments and numpy docstring rendering -- things are pretty different. I don't think that our original design decision makes sense. So I've changed it in master to show the whole docstring. If it turns out that it's not ideal in some situations, we could always add a param to showdoc to make it optional.

To render it better in HTML we'd need to replace 2+ CRs with <p> tags, or similar. Feel free to PR that if it's something you need.