pydoc-markdown
pydoc-markdown copied to clipboard
Using google style docstrings raises entries gain names of variables sometimes
Environment
- Pydoc-Markdown Version: v4.8.2
- Python Version: v3.9.16
- Operating System: Windows 11
Describe the bug
Some markdown files that are generated form google style docstrings contains variable names instead of raised error types in the Raises section.
Example:
class TestDocumentation:
def __init__(
self,
a: int,
b: int = 2,
c: Union[Path, str] = None,
d: Union[Path, str] = None,
e: Union[Path, str] = None,
):
"""
Long summary of the class. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ullamcorper, libero in
pellentesque ultricies, nunc libero tincidunt tellus, sed "suscipit odio" magna eget nisl. Nullam vel magna eget
urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Args:
a (int): Very long description of a. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero
b (int, optional): Even longer description of b. "Lorem" ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to 2.
c (Union[Path, str], optional): Description of c. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
d (Union[Path, str], optional): Description of d. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
e (Union[Path, str], optional): Description of e. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
Raises:
FileNotFoundError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
IsADirectoryError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
TypeError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
ValueError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
TypeError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
KeyError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
KeyError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
ValueError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
ValueError: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
"""
pass
Generated markdown:
```python
class TestDocumentation()
```
### \_\_init\_\_
```python
def __init__(a: int,
b: int = 2,
c: Union[Path, str] = None,
d: Union[Path, str] = None,
e: Union[Path, str] = None)
```
Long summary of the class. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ullamcorper, libero in
pellentesque ultricies, nunc libero tincidunt tellus, sed "suscipit odio" magna eget nisl. Nullam vel magna eget
urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
**Arguments**:
- `a` _int_ - Very long description of a. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero
- `b` _int, optional_ - Even longer description of b. "Lorem" ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to 2.
- `c` _Union[Path, str], optional_ - Description of c. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
- `d` _Union[Path, str], optional_ - Description of d. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
- `e` _Union[Path, str], optional_ - Description of e. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
**Raises**:
- `FileNotFoundError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `IsADirectoryError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `TypeError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `TypeError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `b`0 - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `b`0 - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Expected behavior
```python
class TestDocumentation()
```
### \_\_init\_\_
```python
def __init__(a: int,
b: int = 2,
c: Union[Path, str] = None,
d: Union[Path, str] = None,
e: Union[Path, str] = None)
```
Long summary of the class. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ullamcorper, libero in
pellentesque ultricies, nunc libero tincidunt tellus, sed "suscipit odio" magna eget nisl. Nullam vel magna eget
urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
**Arguments**:
- `a` _int_ - Very long description of a. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero
- `b` _int, optional_ - Even longer description of b. "Lorem" ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to 2.
- `c` _Union[Path, str], optional_ - Description of c. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
- `d` _Union[Path, str], optional_ - Description of d. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
- `e` _Union[Path, str], optional_ - Description of e. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
ullamcorper, libero in pellentesque ultricies, nunc libero tincidunt tellus, sed suscipit odio magna
eget nisl. Nullam vel magna eget urna consectetur aliquet. Sed sed nisl euismod, ultrices nunc
Defaults to None.
**Raises**:
- `FileNotFoundError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `IsADirectoryError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `TypeError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `TypeError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `KeyError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `KeyError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- `ValueError` - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Not sure what causes this it was quite difficult to reproduce the error. I see this issue appearing all over my generated documentation.
I've seen this as well - for some reason it seems to often be the second arg in the list that gets repeated later, with a number appended to it.
I believe it's related to the escape_html_in_docstring parameter in MarkdownRenderer. When this is set to true (as is default for DocusaurusRenderer) it results in the buggy docstrings.
Still got this issue - for any number of args > 10 I find that the 2nd one is repeated for 10th value onwards. Only way to fix is to set escape_html_in_docstring: false