search

NiklasRosenstein / pydoc-markdown

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

Using google style docstrings raises entries gain names of variables sometimes #297

Open aukselis-c1connections opened 1 year ago

aukselis-c1connections commented 1 year ago

Environment

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.

RLesser commented 8 months ago

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.

JoshC8C7 commented 5 months ago

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