L'autodoc di Sphinx non è abbastanza automatico

Question

Sto provando a usare Sphinx per documentare un progetto di oltre 5.000 linee in Python. Ha circa 7 moduli base. Per quanto ne so, Per poter utilizzare autodoc ho bisogno di scrivere codice come questo per ogni file nel mio progetto:

.. automodule:: mods.set.tests 
    :members: 
    :show-inheritance: 

questo è il modo troppo noioso perché ho molti file. Sarebbe molto più semplice se potessi semplicemente specificare che volevo che il pacchetto "mods" fosse documentato. Sfinge potrebbe quindi ricorsivamente passare attraverso il pacchetto e creare una pagina per ogni sottomodulo.

C'è una funzionalità come questa? Altrimenti potrei scrivere uno script per creare tutti i file .rst, ma ciò richiederebbe molto tempo.

Answer 1

È possibile controllare questo script che ho fatto. Penso che possa aiutarti.

Questo script analizza un albero di directory alla ricerca di moduli e pacchetti python e crea file di ripristino in modo appropriato per creare la documentazione del codice con Sphinx. Crea anche un indice di moduli.

UPDATE

questo script è ora parte della Sfinge 1.1 come apidoc.

Answer 2

In ogni pacchetto, il file __init__.py può avere componenti .. automodule:: package.module per ciascuna parte del pacchetto.

Quindi è possibile .. automodule:: package e fa principalmente quello che vuoi.

Answer 3

Forse quello che stai cercando è Epydoc e questo Sphinx extension.

Answer 4

Non so se Sphinx avesse avuto l'estensione autosummary al momento della domanda originale, ma per ora è abbastanza possibile impostare una generazione automatica di questo tipo senza usare lo sphinx-apidoc o uno script simile. Di seguito ci sono le impostazioni che funzionano per uno dei miei progetti.

1. Abilita autosummary estensione (così come autodoc) in conf.py file e impostare l'opzione autosummary_generate-True. Questo potrebbe essere sufficiente se non si utilizzano modelli personalizzati *.rst. Altrimenti aggiungi la tua directory modelli per escludere l'elenco, oppure autosummary proverà a trattarli come file di input (che sembra essere un bug).

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] 
   autosummary_generate = True 
   templates_path = [ '_templates' ] 
   exclude_patterns = ['_build', '_templates'] 
   

2. Usa autosummary:: in albero di TOC nel file index.rst. In questo esempio, la documentazione per i moduli project.module1 e project.module2 verrà generata automaticamente e inserita nella directory _autosummary.

   PROJECT 
   ======= 
   
   .. toctree:: 
   
   .. autosummary:: 
       :toctree: _autosummary 
   
       project.module1 
       project.module2 
   

3. Per default autosummary genererà solo sintesi molto brevi per i moduli e le loro funzioni.Per cambiare che si può mettere un file di modello personalizzato in _templates/autosummary/module.rst (che verrà analizzato con Jinja2):

   {{ fullname }} 
   {{ underline }} 
   
   .. automodule:: {{ fullname }} 
       :members: 
   

In conclusione, non v'è alcuna necessità di mantenere _autosummary directory sotto controllo di versione. Inoltre, puoi nominarlo come vuoi e posizionarlo ovunque nell'albero dei sorgenti (ma non lo puoi applicare al di sotto di _build).