Come devo documentare elenchi, optionals e rendimenti usando la Sfinge di stile Google?

Question

Come si indicano tipi di elenchi, argomenti facoltativi e tipi di restituzione per generatori su docstring in stile Google utilizzando Sphinx-Napoleon?

Ho provato rispettivamente

List[type] 
list of type 

Optional[type] 
type, optional 

e

Yields: 
    type: 

; ma tutti producono risultati insoddisfacenti che non sono coerenti con il resto della documentazione generata. Per esempio

Optional[type] 

solo dà

opzionale [type]

senza alcun collegamento per type.

Ho provato tutti i temi di costruzione e ho gli stessi problemi.

Come dovrei documentare questi elementi utilizzando docstring in stile Google con Sphinx-Napoleon?

Answer 1

So che questo è piuttosto vecchio, ma hai dato un'occhiata a this example? In particolare le linee:

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."""