[Feature Request] [LSP] [docstrings] Better Markdown support for arbitrary section headers, correct `<ul>` rendering, and standardization of section ordering

[martinvuyk]

Review Mojo's priorities

• [X] I have read the roadmap and priorities and I believe this request falls within the priorities.

What is your request?

Overall the experience with docstrings is great. Though I think arbitrary headers should be rendered in the same size and bold text as standard ones, and - should always be rendered as <ul> after all section headers

A classic Python docstring section header that is not in the "standard" Mojo headers:

fn _utf8_byte_type(b: SIMD[DType.uint8, _], /) -> __type_of(b):
    """UTF-8 byte type.

    Returns:
        The byte type.

    Notes:
        - 0 -> ASCII byte.
        - 1 -> continuation byte.
        - 2 -> start of 2 byte long sequence.
        - 3 -> start of 3 byte long sequence.
        - 4 -> start of 4 byte long sequence.
    """

it does work if you add a newline, but it renders weirdly

fn _utf8_byte_type(b: SIMD[DType.uint8, _], /) -> __type_of(b):
    """UTF-8 byte type.

    Returns:
        The byte type.

    Notes:

        - 0 -> ASCII byte.
        - 1 -> continuation byte.
        - 2 -> start of 2 byte long sequence.
        - 3 -> start of 3 byte long sequence.
        - 4 -> start of 4 byte long sequence.
    """

And something uglier, it renders better but wrong size font

fn _utf8_byte_type(b: SIMD[DType.uint8, _], /) -> __type_of(b):
    """UTF-8 byte type.

    Returns:
        The byte type.

    #### Notes:
    ```markdown
        - 0 -> ASCII byte.
        - 1 -> continuation byte.
        - 2 -> start of 2 byte long sequence.
        - 3 -> start of 3 byte long sequence.
        - 4 -> start of 4 byte long sequence.
    ```
    """

And another option that works well but breaks away from the docstring aesthetic

fn _utf8_byte_type(b: SIMD[DType.uint8, _], /) -> __type_of(b):
    """UTF-8 byte type.

    Returns:
        The byte type.

    - Notes:
        - 0 -> ASCII byte.
        - 1 -> continuation byte.
        - 2 -> start of 2 byte long sequence.
        - 3 -> start of 3 byte long sequence.
        - 4 -> start of 4 byte long sequence.
    """

What is your motivation for this change?

Arbitrary section headers should be rendered bellow "standard" Mojo headers like they currently do, but should keep the same aesthetic while writing them and functionality when rendering.

Any other details?

If there is any way shape or form that I can contribute code to the cause I'll gladly help since I think this is worthwhile for the long term consistency and beauty of Mojo documentation (also making it easier to write tools around it). I also see some need in the future for docstrings to reference modules or functions with hyperlinks which is currently not supported, and many other QoL features that I think will be helpful.

This is something that might seem unimportant to many people but is one of the biggest weaknesses in Python IMO; the fragmentation in docstring standards, and ugly solutions to the parsing problem by standards like sphynx are symptoms of problems with consistency and standardization.

I would even go so far as to propose docstring warnings when non-standard headers get put above standard ones, as I've already seen a bunch of non-standard headers (also some standard headers in non-standard order) all over the stdlib especially in the fast moving modules where nobody wants to nitpick every single PR's docstrings. Also small details like a newline at the start of the summary field which just irks me.