Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support indented (unfenced) code blocks #80

Open
chuckwondo opened this issue Aug 8, 2024 · 1 comment
Open

Support indented (unfenced) code blocks #80

chuckwondo opened this issue Aug 8, 2024 · 1 comment
Labels
feature Request for new feature or improvement

Comments

@chuckwondo
Copy link

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:

"""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

@chuckwondo chuckwondo added the feature Request for new feature or improvement label Aug 8, 2024
@jgd10
Copy link

jgd10 commented Oct 9, 2024

I have also encountered this bug! It would be great to fix it as I am trying to avoid building my docs as markdown with sphinx and other than this issue it works great.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature Request for new feature or improvement
Projects
None yet
Development

No branches or pull requests

2 participants