ml-tooling / lazydocs

📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.
MIT License
205 stars 38 forks source link

Incorrect markdown generated for fenced code blocks containing doctest tests #79

Open chuckwondo opened 3 months ago

chuckwondo commented 3 months ago

Describe the bug:

When a fenced code block includes a doctest test (specifically >>> prompts), the generated markdown is incorrect.

Expected behaviour:

Fenced code blocks containing >>> should render just like any other fenced code block.

For example, this docstring:

"""Compute the sum of 2 numbers.

Examples:

```plain
>>> add(1, 2)
3
>>> add(2, 2)
4

"""


should generate the following markdown:

Compute the sum of two numbers.

Examples:

>>> add(1, 2)
3
>>> add(2, 2)
4

Unfortunately, it produces the following instead:

Compute the sum of two numbers.

Examples:

``` add(1, 2)``` 3 ``` add(2, 2)```
4


And the resulting HTML does not render as expected.

**Steps to reproduce the issue:**

<!-- include screenshots, logs, code or other info to help explain your problem.

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
-->

See example docstring above.

**Technical details:**

- Host Machine OS (Windows/Linux/Mac): Mac
- Browser (Chrome/Firefox/Safari): Any

**Possible Fix:**

<!--- Not obligatory, but suggest a fix or reason for the bug -->
I have not looked at the lazydocs code, so I don't know, but happy to dig in, if it would help.

**Additional context:**

<!-- Add any other context about the problem here. -->
None
chuckwondo commented 3 months ago

Hmmm, I just discovered this: https://github.com/ml-tooling/lazydocs/blob/v0.4.8/src/lazydocs/generation.py#L366-L368

At first glance, this appears to be incorrect, but I'll investigate further.

github-actions[bot] commented 4 days ago

This issue is stale because it has been open 90 days with no activity. Remove stale label or comment or this will be closed in 14 days