René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"change: Collect and concat footnotes/references when rendering sections or partial docstrings","articleBody":"### Is your change request related to a problem? Please describe.\r\nContext: https://github.com/Python-Markdown/markdown/issues/1495.\r\n\r\nIf 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.\r\n\r\n### Describe the solution you'd like\r\nThe 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.\r\n\r\n- Concatenation: `\"\\n\\n\".join(section.value for section in sections if section.kind is DocstringSectionKind.text)`\r\n- Retrieval of first paragraph: use standard lib's HTML parser, feed the result to it, record only first `p` element and break\r\n\r\n### Describe alternatives you've considered\r\nDocumenting 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.\r\n\r\nAnother 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.\r\n\r\n### Additional context\r\nI 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.","author":{"url":"https://github.com/pawamoy","@type":"Person","name":"pawamoy"},"datePublished":"2024-12-13T17:34:00.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/217/python/issues/217"}