tipi metodo di ritorno sphinx con collegamenti

Question

Uso Cython insieme -Xembedsignature=True può produrre segnature docstring sotto forma di:

| mymethod(...) 
|  MyCythonModule.mymethod(self, param1, MyCythonType param2, param3=None) -> SomeResultType 

Quando genera documentazione Sphinx per questo utilizzando l'estensione autodoc qualcosa di simile è l'output:

mymethod(self, param1, MyCythonType param2, param3=None) → SomeResultType 

Il problema è che né MyCythonType né SomeResultType sono collegamenti ipertestuali nella documentazione HTML, il che rende la documentazione un po 'sub-ottimale da esplorare.

Sphinx offre allo sviluppatore della documentazione la possibilità di collegarsi all'evento 'autodoc-process-signature', che consente di manipolare la firma al volo. Il metodo dovrebbe restituire una tupla (signature, return_annotation). Quando si modifica il risultato return_annotation per inserire elementi come `SomeResultType`, o: class: SomeResultType ecc, semplicemente non è formattato ma finisce nella documentazione HTML così com'è, senza collegamenti e con qualsiasi cosa sia stata aggiunta/anteposta alla stringa.

Vedo che il parametro digitato potrebbe dover essere ignorato, poiché Python non ha nulla di simile, ma è necessario ottenere un collegamento ipertestuale per il tipo restituito alla documentazione della classe, ma sono fuori di idee .

Dopo aver scritto un piccolo banco di prova sembra come questo influisce Python così, e non solo Cython:

class Foo(object): 
     def __init__(self): 
       pass 

     def get_bar(self): 
       """ 
       get_bar(self) -> Bar  <- here you see 'Bar', it will not 
              become a hyperlink, not even if 
              enclosed in `` 

       Get `Bar` from foo  <- here you see Bar again, it will 
              become a hyperlink 

       :returns: the bar 
       """ 
       return Bar() 

class Bar(object): 
     def __init__(self): 
       pass 

Answer 1

Invece di :returns: the bar si dovrebbe cercare :class:`Bar` invece.

Quindi, in questo modo:

class Foo(object): 
    def __init__(self): 
      pass 

    def get_bar(self): 
      '''Get :class:`Bar` from :class:`Foo` 

      :returns: the :class:`Bar` 
      ''' 
      return Bar() 


class Bar(object): 
    def __init__(self): 
      pass