NiklasRosenstein / pydoc-markdown

Create Python API documentation in Markdown format.
http://niklasrosenstein.github.io/pydoc-markdown/
Other
458 stars 102 forks source link

Indentation inside Sphinx code blocks is ignored #179

Closed igrr closed 3 years ago

igrr commented 3 years ago

I recently ran into an issue with Sphinx code blocks, similar to the one being fixed in #169. Given the following example docstring:

def awesome(foo):
    """
    An awesome context manager

    Example usage:
with awesome(foo) as aww:
    aww.dostuff()
```
:param foo: whatever you want to make awesome
:return: an instance of awesomeness
"""
pass
i get the following markdown as output. Note that the 2nd line of the code block is not indented:
```md

    ```python
    awesome(foo)
An awesome context manager

Example usage:
```
with awesome(foo) as aww:
aww.dostuff()
```

**Arguments**:

- `foo`: whatever you want to make awesome

**Returns**:

an instance of awesomeness

It seems that the reason is an over-eager line.strip here:
https://github.com/NiklasRosenstein/pydoc-markdown/blob/9532ac8abc15970e8e861e9618138c0fa6c3582f/pydoc-markdown/src/pydoc_markdown/contrib/processors/sphinx.py#L80

Additionally, the subsequent `line_codeblock = line.startswith('    ')` has no effect since `line` has already been stripped.

Modifying the code as follows seems to produce desired *(by me)* behavior:
```python
    for line in node.docstring.split('\n'):
      if line.strip().startswith("```"):
        in_codeblock = not in_codeblock

      line_codeblock = line.startswith('    ')

      if not in_codeblock and not line_codeblock:
        line = line.strip()

Please let me know if I'm misunderstanding the desired behavior. I can open a PR with this change if it looks reasonable.

NiklasRosenstein commented 3 years ago

Hey @igrr , looks to me like your suggested change makes sense. Could you open a PR and add a test case?

Thanks!