Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
aukselis-c1connections opened this issue Jul 11, 2023 · 2 comments
Assignees
Labels

Comments

@aukselis-c1connections
Copy link

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.

@RLesser
Copy link

RLesser commented Nov 13, 2023

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
Copy link

JoshC8C7 commented Jan 18, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

4 participants