pydoc-markdown icon indicating copy to clipboard operation
pydoc-markdown copied to clipboard

Using google style docstrings raises entries gain names of variables sometimes

Open aukselis-c1connections opened this issue 2 years ago • 2 comments

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.

aukselis-c1connections avatar Jul 11 '23 13:07 aukselis-c1connections

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.

RLesser avatar Nov 13 '23 20:11 RLesser

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

JoshC8C7 avatar Jan 18 '24 17:01 JoshC8C7