How should I document lists, optionals, and yields using Google-style Sphinx?

Question

How do I indicate types for lists, optional arguments and return types for generators on Google-style docstrings using Sphinx-Napoleon?

I've tried

List[type]
list of type

Optional[type]
type, optional

and

Yields:
   type:

respectively; but all produce unsatisfactory output that is not consistent with the rest of the generated documentation. For example

Optional[type]

just gives

Optional[type]

without any link for type.

I've tried every builtin theme and have the same issues.

How should I be documenting these elements using Google-style docstrings with Sphinx-Napoleon?

Maybe here you can find something: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html — Ceppo93, Jul 21 '16 at 06:28
Because the page is full of examples of sphinx docstrings using the Google-style? — Ceppo93, Jul 21 '16 at 14:29
@Ceppo93 - but the question was why those examples don't (or didn't) work. — orome, Jul 21 '16 at 14:31
_**How** should I be documenting these elements using Google-style docstrings with Sphinx-Napoleon?_ anyway if you look at the examples those elements are documented diffrently than yours — Ceppo93, Jul 21 '16 at 14:35
@Ceppo93 - Are the results different from what the question describes? That's what I was asking in my comet. — orome, Jul 21 '16 at 14:59
I don't see any links in my resulting sphinx html documents, but with my IDE I have links on some fields and not others. — Bamcclur, Jan 11 '17 at 19:24

score 3 · Answer 1 · answered Sep 08 '17 at 19:40

I know this is quite old, but did you take a look at this example? Particularly lines:

def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        The __init__ method may be documented in either the class level
        docstring, or as a docstring on the __init__ method itself.

        Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the __init__ method and be consistent with it.

        Note:
            Do not include the `self` parameter in the ``Args`` section.

        Args:
            param1 (str): Description of `param1`.
            param2 (:obj:`int`, optional): Description of `param2`. Multiple
                lines are supported.
            param3 (:obj:`list` of :obj:`str`): Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

        self.attr5 = None
        """str: Docstring *after* attribute, with type specified."""

How should I document lists, optionals, and yields using Google-style Sphinx?

1 Answers1