I would like to use reStructuredText, Sphinx, and Sphinx autodoc for Python code in the same way one uses Javadoc for Java code, that is, for specifying parameters and return values, but also for linking to other classes, methods, etc.
I am finding it very hard to find a reference for learning how to do this. The Sphinx documentation mentions :param and :return: in passing, as mere examples of field lists. I cannot find a proper reference for these roles (and similar ones I imagine exist, such as one for "see also") anywhere.
More importantly, I find it unclear how to create links for other classes and methods, especially if those are in other packages.
Is this the main way Python developers extract documentation from source code? If so, I would expect some clear documentation and reference for this purpose somewhere.
Update: please note that I don't mean the autodoc reference. This page explains how to import docstrings into arbitrary Sphinx documents. It does not explain which roles can be used in docstrings to document parameters, return values, types, or to link to other methods and classes. For instance, a search on this page for :param does not find anything.
ReST fields such as param and return that can be used in docstrings are described under "Info field lists" in the "Python domain" section: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists.
The roles that are available for creating cross-references to documented Python objects are described here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects.
You should also take a look at the Napoleon extension, which supports docstring styles that many people find more legible: https://sphinx-doc.org/en/master/usage/extensions/napoleon.html.