bug: Return type in docstring rendered like a parameter name

[jayqi]

Description of the bug

When using Google-style docstrings with the optional return type, the return type is rendered as if it's a parameter name.

To Reproduce

This docstring:

def format_version(version: Version, format_string: str) -> str:
    """Format a version using a format string.

    Args:
        version (packaging.version.Version): The version to format.
        format_string (str): The format string to use.

    Returns:
        str: The formatted version.
    """

Produces this output:

### vspect.format_version

```python
format_version(version, format_string)
```

Format a version using a format string.

**Parameters:**

- **version** (<code>[Version](#packaging.version.Version)</code>) – The version to format.
- **format_string** (<code>[str](#str)</code>) – The format string to use.

**Returns:**

- **str** (<code>[str](#str)</code>) – The formatted version.

The package that I ran this on can be found here

Expected behavior

I expect the rendered return to look something like this:

- <code>[str](#str)</code> – The formatted version.

which is what get if my original docstring excluded the optional return type.

Environment information

• System: macOS-14.7.2-x86_64-i386-64bit-Mach-O
• Python: cpython 3.13.0 (/Users/jqi/vspect/.venv/bin/python3)
• Environment variables:
• Installed packages:
  • griffe2md v1.1.0

[pawamoy]

Hey @jayqi, thanks for the report.

This behavior is expected (although a bit counter-intuitive probably); items in Returns section can be named by default, meaning you need to wrap the type in parentheses so that it's not parsed as a name:

def format_version(version: Version, format_string: str) -> str:
    """Format a version using a format string.

    Args:
        version (packaging.version.Version): The version to format.
        format_string (str): The format string to use.

    Returns:
        (str): The formatted version.
    """

This is counter-intuitive because that's not what the Google-style guide describes. We felt like this was the most consistent syntax though.

If the workaround of updating your docstrings is acceptable to you, let me know, otherwise we can think about adding a way for users to pass options from the CLI, or when using griffe2md programmatically (in the latter case, we can already pass the style options but not further parsing options like returns_named_value).

[jayqi]

Ah, I see. Thanks for pointing to the relevant Griffe documentation. It looks mkdocstrings parses and outputs things in the same way, but I just hadn't noticed until now.

It's a little annoying to have to deviate from standard Google-style syntax, but that's not a hill I need to die on. Having a way to specify options would certainly be nice though!

[pawamoy]

Noted! 🙂