Come evitare gli avvisi di "SEVERE: Duplicate ID" per i miei moduli autodoc'd in Sfinge?

Question

Sto usando RST/Sfinge per documentare il mio Python, tuttavia quando la costruzione è lanciando avvertimenti come

...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast". 

file sorgenti mio Python sono documentati in questo modo:

#!/usr/bin/env python 
''' 
.. module:: toast 
    :synopsis: Processes the blobs produced by :mod:`bread`. 
''' 
# my inline-rST documented code... 

E i file di RST usare l'autodoc ha fornito la direttiva automodule per estrarre tutte le docstring e documentare tutti i membri.

Toast 
-------------------------------- 

.. automodule:: toast 
    :members: 

È possibile che questo combo sembra funzionare bene, ma l'errore sembra implicare c'è un modo corretto di fare questo. Se rimuovo la direttiva del modulo dalla parte superiore del mio file sorgente, l'errore scompare, ma non posso aggiungere una sinossi nell'origine che viene rilevata da Sphinx.

Answer 1

Non sono sicuro, ma credo che la direttiva automodule creerà una direttiva module su proprio. Quindi, dal momento che ne hai già uno specificato, ce ne sono due, e quindi ottieni un messaggio ID duplicato.

Si potrebbe provare a utilizzare la direttiva currentmodule nel markup del modulo anziché module. Sembra che il dovrebbe funzionare, anche se ammetto che in realtà non l'ho provato.

Answer 2

Un modo per aggirare è utilizzare la bandiera :noindex:.

.. automodule:: toast 
    :members: 
    :noindex: 

Poi nel codice sorgente si può usare:

#!/usr/bin/env python 
''' 
.. module:: toast 
    :synopsis: Processes the blobs produced by :mod:`bread`. 
''' 

Non ci sarà appariranno alcun avvertimento SEVERE ed il messaggio in sinossi in indice di modulo.

Dall'altro lato :noindex: nasconde il modulo dall'indice se non ha .. module:: nel file di origine.

Answer 3

Il :noindex: per automodule:: come scritto da simno aiuta ma impedisce la creazione di collegamenti perma e collegamenti incrociati (ad esempio :func:) non funzionerà. Quando si aggiunge :noindex: a module::, tutto funziona come previsto e non è necessario utilizzare currentmodule.