Come faccio a fare riferimento a un parametro della funzione Python documentato usando il markup Sphinx?

Question

Vorrei fare riferimento a un parametro di funzione precedentemente documentato altrove in una docstring Python. Si consideri il seguente (per ammissione del tutto artificiale) Esempio:

def foo(bar): 
    """Perform foo action 
    :param bar: The bar parameter 
    """ 

    def nested(): 
     """Some nested function that depends on enclosing scope's bar parameter. 
     I'd like to reference function foo's bar parameter here 
     with a link, is that possible?""" 
     return bar * bar 

    # ... 
    return nested() 

C'è un modo semplice per incorporare un riferimento parametro utilizzando Sfinge markup, o accadrà questo automagically?

(io sono un newbie completo Sfinge. Ho la scansione dei documenti Sphinx e non ho trovato una risposta a questa domanda, o un esempio che illustra la corretta marcatura.)

Answer 1

Ho appena creato un'estensione per eseguire questa operazione. Finora sembra che stia lavorando con la build HTML autonoma e in aggiunta con readthedocs (dopo alcune modifiche aggiuntive).

l'estensione è disponibile a: https://pypi.python.org/pypi/sphinx-paramlinks/.

Lo sto lanciando proprio ora per i progetti Alembic e SQLAlchemy. (sample).

Sono in disaccordo con il suggerimento che il collegamento a parametri indica che i documenti sono troppo lunghi. La libreria standard Python è un pessimo esempio in questo caso poiché le funzioni stdlib sono necessariamente granulari e semplici. Il software che sta svolgendo un'attività più grossolana, in cui una singola funzione si basa su un problema complesso da risolvere, avrà spesso parametri che richiedono molte più spiegazioni; questa spiegazione è spesso abbastanza valida come soluzione a un problema particolare altrove, e quindi essere in grado di collegarsi ad essa è molto importante.

Answer 2

Se siete alla ricerca di un il modo per collegarsi direttamente alla definizione bar di foo quindi la tua documentazione è troppo lunga o stai chiedendo al tuo lettore di ignorare la foresta per un albero o una combinazione dei due.

Prendendo un esempio dal defaultdict Examples:

Setting the :attr:`default_factory` to :class:`int` makes the 
:class:`defaultdict` useful for counting (like a bag or multiset in other 
languages): 

se non posso essere preso la briga di leggere cinque frasi in collections.defaultdict per trovare il significato di default_factory probabilmente non merito di essere portare lì.

noti che la sintassi di riferimento attributo è la stessa come nella sezione precedente:

The first argument provides the initial value for the :attr:`default_factory` 
attribute; it defaults to ``None``. 

ma sembra Sfinge non raggiunge fuori dell'ambito sezione corrente e quindi rende il riferimento in seguito come testo formattato piuttosto che come un'ancora. Non mi sorprenderebbe se fosse intenzionale.

Answer 3

Non esiste un modo semplice per ottenere un riferimento diretto a un parametro di una funzione con sphinx e non conosco un'estensione per questo problema.

Il documentation of the python domain spiega quali oggetti possono essere incrociati.

Un modo possibile per dare all'utente un riferimento al parametro bar della funzione foo sarebbe

See parameter ``bar`` in :func:`foo`. 

Forse un riferimento diretto sarebbe possibile scrivendo un'estensione.