I haven't looked at the lazydocs code, so I don't know whether or not this is a bug. Given what I've seen via some experimentation (not detailed here), it appears that this may be something currently not implemented, rather than a bug, but that's just an educated guess from what I'm seeing as output, not from looking at the code.
Problem and motivation:
Including doctests in docstrings can be extremely valuable (ref: https://docs.python.org/3/library/doctest.html), but lazydocs does not recognize them, and thus does not handle them specially, so they are not rendered properly if they are not somehow distinguished from surrounding text.
This should work in 2 ways, without the need for any special handling: (a) place doctests within a fenced code block, or (b) place them within a plain (unfenced), indented block (at least 4 spaces or a tab) indented from the surrounding text.
Unfortunately, neither works with lazydocs. Plain, unfenced, indented blocks are not recognized at all, and are simply treated as any other text, indented or not. Fenced code blocks don't work when they contain >>> (see #79).
For example, this docstring:
"""Compute the sum of 2 numbers.
Examples:
>>> add(1, 2)
3
>>> add(2, 2)
4
"""
Should generate markdown similar to the following:
Compute the sum of two numbers.
**Examples:**
>>> add(1, 2)
3
>>> add(2, 2)
4
Instead, this is what is generated:
Compute the sum of two numbers.
**Examples:**
``` add(1, 2)```
3
>>> add(2, 2)
4
Is this something you're interested in working on?
yes, although I'll likely need some pointers on getting started
Feature description:
Support basic (unfenced) code blocks via indentation (at least 4 spaces or a tab), as per https://www.markdownguide.org/basic-syntax/#code-blocks.
I haven't looked at the lazydocs code, so I don't know whether or not this is a bug. Given what I've seen via some experimentation (not detailed here), it appears that this may be something currently not implemented, rather than a bug, but that's just an educated guess from what I'm seeing as output, not from looking at the code.
Problem and motivation:
Including doctests in docstrings can be extremely valuable (ref: https://docs.python.org/3/library/doctest.html), but lazydocs does not recognize them, and thus does not handle them specially, so they are not rendered properly if they are not somehow distinguished from surrounding text.
This should work in 2 ways, without the need for any special handling: (a) place doctests within a fenced code block, or (b) place them within a plain (unfenced), indented block (at least 4 spaces or a tab) indented from the surrounding text.
Unfortunately, neither works with lazydocs. Plain, unfenced, indented blocks are not recognized at all, and are simply treated as any other text, indented or not. Fenced code blocks don't work when they contain
>>>(see #79).For example, this docstring:
Should generate markdown similar to the following:
Instead, this is what is generated:
Is this something you're interested in working on?
yes, although I'll likely need some pointers on getting started