Sto provando a documentare un pacchetto python con sphinx e ho generato correttamente file html. Il pacchetto che sto documentando consiste in un insieme di file *.py, la maggior parte dei quali contiene una classe con un paio di file che sono moduli originali con funzioni definite. Non è necessario esporre il fatto che ogni classe è in un modulo, quindi ho aggiunto le dichiarazioni from appropriate nel file __init__.py ad es.Come si documentano le classi senza il nome del modulo?
from base import Base
in modo che l'utente può utilizzare il comando import pkg e non quindi necessario specificare il modulo che contiene la classe:
import pkg
class MyBase(pkg.Base): # instead of pkg.base.Base ...
...
Il problema è che sfinge insiste sul documentare la classe come pkg.base.Base. Ho provato a impostare il add_module_names = False in conf.py. Tuttavia, ciò risulta sfinge che mostra la classe semplicemente come Base anziché pkg.Base. Inoltre questo rovina anche la documentazione della coppia di file *.py che i moduli sono.
Come faccio a creare sphinx come classe pkg.Base? E come si imposta la direttiva add_module_names in modo selettivo per ogni file *.py?
Non farlo. Sphinx ** correttamente ** dice all'utente dove la classe è * definita *, non dove è importata. Se importerai la classe 'Base' in due diversi moduli, in che modo Sphinx può dire quale nome vuoi usare? Se non vuoi che l'utente sappia del modulo in cui definisci la classe, probabilmente dovresti renderlo privato (il che, se ricordo bene, non verrà mostrato nei file generati). – Bakuriu
@Bakuriu - Non sono sicuro di aver capito il tuo commento. Per chiarire, l'unica ragione per cui ogni classe si trova in un file separato è rendere più facile la gestione del controllo del codice sorgente di fronte. L'utilizzo delle classi richiede solo i nomi di pacchetto e classe e non il nome del modulo (che è ridondante). La documentazione dovrebbe descrivere l'uso e non la definizione, non credi? Come si rende privato il nome del modulo? –
Allora qual è il problema? Basta usare 'add_module_names = False' e posizionare la documentazione nella pagina corretta. Gli utenti vedranno che nella pagina che si riferisce al modulo 'pkg' c'è una' Base' documentata e va bene. Il 'pkg.module.Base' ** solo ** si riferisce al modulo in cui è definita la classe, non dove lo si" usa "(che è qualcosa di non ben definito). Se vuoi una soluzione sporca per ottenere l'output desiderato, in '__init__' crea una sottoclasse falsa:' class TheClass (pkg.module.TheClass): pass', ereditando la documentazione. – Bakuriu