Return type inline in return

[arthur-tacca]

I know I'm worrying over a triviality, but I find it a bit offensive that the return type has its own line, when the type of parameters and exceptions is inline:

I'm happy to work around this by manually putting the return type in the description of :return: but then it looks very different to in the parameters and exceptions. (Actually even those are different from each other - bold vs italic - but this is monospace and boxed so looks even more different):

I think it would be good to be able to fold return type into the return item automatically. I'd be interested in any workaround ideas too.

[AA-Turner]

Are you using :rtype:? Please provide a reproducible example.

A

[arthur-tacca]

Yes the above example was just using :rtype: manually:

.. function:: my_test_fn(param1, param2)

   Example of documentation for a function.

   :param param1: Description of first parameter.
   :type param1: int | str
   :param param2: The second parameter.
   :type param2: ResultCapture
   :return: The result of the function.
   :rtype: ResultCapture
   :raise TaskNotDoneException: When an error happens.

But the same thing happens with autodoc and autodoc_typehints = "description". The second example is using a normal reference in :return::

   :return: :class:`ResultCapture` -- The result of the function.

Edit: Oh, and I should mention that I'm using the ReadTheDocs theme, though I don't think that fundamentally changes anything.

[AA-Turner]

Does using :return ResultCapture: The result of the function. work?

xref https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists

A

[arthur-tacca]

I can't test or post a screenshot right now, but I'm pretty sure I tried it earlier and it didn't work. I think that's because :return: is defined to be a sphinx.util.docfields.Field with has_arg=False.

[arthur-tacca]

Actually the temptation is to monkey patch that list with an extra entry that is a PyGroupedField like :raise:. I'll give that a go later. It wouldn't help if you're using autodoc though.

[arthur-tacca]

As a workaround, it can be fixed by switching the type of :return: to be the same sort of field as :exception:. This can be done by putting this in this in the conf.py:

from sphinx.domains.python import PyObject, PyGroupedField

for i, f in enumerate(PyObject.doc_field_types):
    if f.name == "returnvalue":
        PyObject.doc_field_types[i] = PyGroupedField(
            f.name, label=f.label, names=f.names, rolename="class", can_collapse=True
        )

Then this Sphinx code:

.. function:: my_test_fn(param1, param2)

   Example of documentation for a function.

   :param param1: Description of first parameter.
   :type param1: int | str
   :param param2: The second parameter.
   :type param2: typing.Callable[[int | str, bool], ResultCapture]
   :return ResultCapture: The result of the function.
   :raise TaskNotDoneException: When an error happens.

gives this output:

As a bonus (depending on your point of view), it will now automatically turn multiple entries into a list. For example, this input:

.. function:: my_test_fn(param1, param2)

   Example of documentation for a function.

   :param param1: Description of first parameter.
   :type param1: int | str
   :param param2: The second parameter.
   :type param2: ResultCapture
   :return ResultCapture: The result of the function.
   :return None: If nothing to return.
   :raise TaskNotDoneException: When an error happens.

gives this output:

I originally thought of adding a totally new type of field, rather than patching the existing :return: meaning, but I've realised that it's harmless to do it this way: if you don't pass an argument then it's the same as it was before. It might even be worth updating Sphinx to do (although I get there could be a backwards-compatibility worry, even if it is presumably very rare to have multiple :return: fields in existing projects).

None of this solves the autodoc issue by itself. That would need additional changes. But this change would at least unlock a mechanism that an autodoc change could use (under a config option of course).