Deduplicate type information in docstrings

[paddyroddy]

Is Your Feature Request Related to a Problem? Please Describe

The problem at the moment is that we have type in the docstrings, and through #308 we are getting static types. However, sometimes there is a mismatch, and the bigger problem is that it is two duplicate things to maintain. If one removes the type as it is currently (I believe numpy style) then we trigger ruff D417. We can enforce the docstring convention through ruff https://docs.astral.sh/ruff/settings/#lintpydocstyle.

Describe the Solution You'd Like

They look like https://google.github.io/styleguide/pyguide.html#244-decision

"""Connects to the next available port.

Args:
  minimum: A port value greater or equal to 1024.

Returns:
  The new minimum port.

Raises:
  ConnectionError: If no available port is found.
"""

The documentation will still show the types.

Describe Alternatives You've Considered

No response

Additional Context

No response

[ntessore]

A solution I have really liked in recent projects is setting autodoc_typehints to "description" in the sphinx config:

# docs/conf.py

...

# -- Options for autodoc -----------------------------------------------------

# This value controls how to represent typehints.
autodoc_typehints = "description"

Then you can use untyped numpy-style docstrings:

def compile(
    expr: str,
    args: Iterable[str] | None = None,
    globals: Mapping[str, Any] | None = None,
    strict: bool = True,
) -> Callable[..., Any]:
    """
    ...

    Parameters
    ==========
    expr:
        Mathematical expression to be parsed and compiled.
    args:
        Parameter names for the compiled lambda function.
    globals:
        Global symbols for the compiled lambda function.
    strict:
        Check names in expression.

    """

And get a nicely typed documentation which uses the correct typing information:

In that case, we can just switch off the ruff rule, since we are relying on the actual static type information.

[paddyroddy]

A solution I have really liked in recent projects is setting autodoc_typehints to "description" in the sphinx config:

Classic sphinx, that is the default behaviour in mkdocs and similar!

[ntessore]

Just to be clear, I would rather not switch from numpy to Google style docstrings. I like the docstring sections, and I think more people are familiar with that style.

[paddyroddy]

Just to be clear, I would rather not switch from numpy to Google style docstrings. I like the docstring sections, and I think more people are familiar with that style.

Do you know how to use it without types? That's the main thing I'm trying to avoid

[ntessore]

Discussed today: we can keep Numpy-style docstrings, but remove the duplicated type information from them.

[paddyroddy]

Discussed today: we can keep Numpy-style docstrings, but remove the duplicated type information from them.

Yep being done in #347 (will edit the title when ready)