change: Render first HTML paragraph instead of first docstring line for summaries

[pawamoy]

Is your change request related to a problem? Please describe.

Context: Python-Markdown/markdown#1495.

If a docstring's first line uses a reference, and that reference is declared in the body, then current summary features will not be able to render the reference.

Describe the solution you'd like

The only way to be more robust is to actually render a concatenation of all text sections found in the docstring, to then retrieve the first HTML paragraph.

• Concatenation: "\n\n".join(section.value for section in sections if section.kind is DocstringSectionKind.text)
• Retrieval of first paragraph: use standard lib's HTML parser, feed the result to it, record only first p element and break

Describe alternatives you've considered

Documenting this as a limitation. Afterall, there are clear semantics for Python docstrings, where the summary is the first line only, separated from the body by a blank line. If the first line depends on the body to be rendered correctly, we could consider it a user error.

Another alternative would be to parse the docstring as Markdown (just parse, not convert) to collect references and footnotes (any other similar item?), to append them back to any summary or text section when rendering.

Additional context

I thought about doing this (first suggestion) for text sections too, when rendering them. However, if we concatenate from the current section down to the last, I don't think it's possible to robustly retrieve just the content of the current section from the resulting HTML. The "collect refs to append back" suggestion would work, though.

[pawamoy]

mistletoe parses Markdown into an AST: https://github.com/miyuchina/mistletoe.

from mistletoe import Document
from mistletoe.ast_renderer import ASTRenderer

markdown = """
This line uses a [link][].

[link]: https://example.com
"""

with ASTRenderer() as renderer:
    print(renderer.render(Document(markdown)))

{
  "type": "Document",
  "footnotes": {
    "link": [
      "https://example.com",
      ""
    ]
  },
  "line_number": 1,
  "children": [
    {
      "type": "Paragraph",
      "line_number": 2,
      "children": [
        {
          "type": "RawText",
          "content": "This line uses a "
        },
        {
          "type": "Link",
          "target": "https://example.com",
          "title": "",
          "children": [
            {
              "type": "RawText",
              "content": "link"
            }
          ]
        },
        {
          "type": "RawText",
          "content": "."
        }
      ]
    }
  ]
}