epydoc - Online nel cloud

PROGRAMMA:

NOME

epydoc - genera la documentazione dell'API dalle docstring di Python

SINOSSI

epidoc [azione] [Opzioni] nomi...

DESCRIZIONE

epidoc genera documentazione API per moduli e pacchetti Python, in base alla loro
docstring. Un linguaggio di markup leggero chiamato epitesto può essere usato per formattare
docstring e per aggiungere informazioni su campi specifici, come parametri e istanze
variabili. Epydoc comprende anche le docstring scritte in ReStructuredText, Javadoc e
testo in chiaro. Attualmente, epydoc supporta due formati di output di base: HTML e LaTeX.

La documentazione API HTML prodotta da epidoc consiste in un insieme di file HTML, tra cui:
una pagina di documentazione API per ogni classe e modulo; una pagina del codice sorgente evidenziata dalla sintassi
per ogni modulo; una pagina di indice identificativo; una pagina di aiuto; e una tabella basata su frame di
Contenuti. Quando appropriato, epidoc genererà anche pagine indice per bug, definito
termini e cose da fare; una pagina di gerarchia di classi; e una pagina della gerarchia dei pacchetti.

La documentazione dell'API LaTeX prodotta da epidoc è costituito da un file LaTeX principale e da un LaTeX
file per ogni modulo. Se usi --dvi, --ps, o --PDF , poi epidoc invocherà esterno
comandi per convertire l'output LaTeX nel formato richiesto. Nota che i file LaTeX
contenente la documentazione per i singoli moduli possono essere inclusi come capitoli o
sezioni di altri documenti LaTeX, utilizzando LaTeX \includere comando. Se lo desideri
includere singole classi in altri documenti LaTeX, quindi utilizzare il pulsante --classi-separate
opzione per produrre un file LaTeX separato per ogni classe.

epidoc può essere utilizzato anche per verificare la completezza della documentazione API. Per impostazione predefinita,
controlla che ogni pacchetto, modulo, classe, metodo e funzione pubblici abbia una docstring
descrizione. Il --test L'opzione può essere utilizzata per specificare ulteriori test da eseguire.

RIPRODUCIBILE COSTRUIRE COMPORTAMENTO

Utilizzando la data corrente all'interno della documentazione generata da Epydoc si ottiene una documentazione che
è "non riproducibile", il che significa che il contenuto dei file cambia da build a build
anche se l'albero di origine non lo fa. Per semplificare la generazione di build riproducibili, questo
versione di Epydoc supporta due funzionalità: il --no-include-tempo di compilazione opzione e il
FONTE_DATE_EPOCA variabile d'ambiente.

. --no-include-tempo di compilazione l'opzione può essere utilizzata quando sai in anticipo che non ti serve
creare timestamp nella documentazione generata. Il FONTE_DATE_EPOCA Industria XNUMX
variabile è destinato all'uso da parte dei sistemi di pacchettizzazione, come il processo di compilazione di Debian.
I sistemi di imballaggio verranno impostati FONTE_DATE_EPOCA a un timestamp ragionevole che sia in qualche modo
relativo allo stato dell'albero dei sorgenti, e quel timestamp sarà usato piuttosto da Eypdoc
rispetto al timestamp corrente. Costruisce usando FONTE_DATE_EPOCA sarà quindi riproducibile.

VERSIONI

Le opzioni di Epydoc sono suddivise in sei categorie: opzioni di base, azioni, generazione
opzioni, opzioni di output, opzioni del grafico e opzioni del valore restituito.

BASIC VERSIONI

nomi...
L'elenco degli oggetti che dovrebbero essere documentati. Gli oggetti possono essere specificati usando
Nomi puntati in Python (come os.percorso), nomi di file (come epydoc/epytext.py),
o nomi di directory (come epidoc/). I nomi delle directory specificano i pacchetti e
sono espansi per includere tutti i sottomoduli e sottopacchetti. Se lo desideri
escludere alcuni sottomoduli o sottopacchetti, utilizzare il pulsante --escludere opzione
(descritto sotto).

--config filetto
Un file di configurazione, specificando addizionale Opzionie / onomi. Questa opzione
può essere ripetuto.

--Q, --calmatevi, --v, --verboso
Produci un output abbastanza (o prolisso). Se usata più volte, questa opzione
produce successivamente un output più silenzioso (o dettagliato).

- debug
Mostra i traceback completi per gli errori interni.

--termine semplice
Non tentare di utilizzare il colore o il controllo del cursore durante la visualizzazione della barra di avanzamento,
avvisi o errori.

AZIONI

--html Scrivi output HTML. [predefinito]

--lattice Scrivi l'output di LaTeX.

--dvi Scrivi l'uscita DVI.

--ps Scrivi output Postscript.

--PDF Scrivi l'output di Adobe Acrobat (pdf).

--dai un'occhiata Eseguire controlli di completezza sulla documentazione.

--salamoia Scrivi la documentazione in un file pickle.

GENERAZIONE VERSIONI

--docformat formato
Imposta il valore predefinito per __formatodoc__ a formato. __formatodoc__ è un modulo
variabile che specifica il linguaggio di markup per le docstring in un modulo.
Il suo valore consiste nel nome di un linguaggio di markup, facoltativamente seguito da a
codice lingua (come en per l'inglese). Per un elenco dei linguaggi di marcatura
attualmente riconosciuto da epydoc, esegui epidoc --Aiuto formato del documento.

--solo analisi
Raccogliere tutte le informazioni sugli oggetti documentati analizzando il relativo
codice sorgente Python; in particolare, fare non è un usa l'introspezione per raccogliere
informazioni sugli oggetti documentati. Questa opzione dovrebbe essere utilizzata quando
epydoc viene eseguito su codice non attendibile; o su codice che non può essere introspettito
a causa di dipendenze mancanti o perché l'importazione causerebbe indesiderate
effetti collaterali.

--solo-introspezione
Raccogliere tutte le informazioni sugli oggetti documentati mediante introspezione; in
particolare, fare non è un raccogliere informazioni analizzando il sorgente Python dell'oggetto
codice.

--escludere MODELLO
Non documentare alcun oggetto il cui nome corrisponda all'espressione regolare data
pattern.

--exclude-introspettivo MODELLO
Non usare l'introspezione per raccogliere informazioni su qualsiasi oggetto il cui nome
corrisponde all'espressione regolare data.

--exclude-analisi MODELLO
Non utilizzare l'analisi del codice sorgente Python per raccogliere informazioni su qualsiasi oggetto
il cui nome corrisponde all'espressione regolare data.

--eredità formato
Il formato da utilizzare per visualizzare metodi, variabili e
proprietà nelle tabelle di "riepilogo" generate. Se formato è "raggruppato", quindi
gli oggetti ereditati vengono raccolti in gruppi, in base alla classe di cui sono
ereditato da. Se formato è "elencato", quindi gli oggetti ereditati sono elencati in a
breve elenco alla fine della tabella riassuntiva. Se formato è "incluso", quindi
gli oggetti ereditati vengono mischiati con gli oggetti non ereditati. Il formato predefinito
per l'output HTML è "raggruppato".

--show-privato, --no-privato
Queste opzioni controllano se la documentazione viene generata per gli oggetti privati.
Per impostazione predefinita, la documentazione generata include oggetti privati ​​e gli utenti possono
scegli se visualizzare o meno gli oggetti privati, cliccando su "mostra privati"
e "nascondi i link privati". Ma se vuoi scoraggiare gli utenti dal diretto
accedere a oggetti privati, allora potresti preferire di non generare documentazione
per oggetti privati.

--show-importazioni, --no-importazioni
Queste opzioni controllano se le importazioni dei moduli sono incluse nel file generato
documentazione. Per impostazione predefinita, le importazioni non sono incluse.

--mostra-codice sorgente, --no-codice sorgente
Queste opzioni controllano se epydoc deve generare o meno la sintassi evidenziata
pagine contenenti il ​​codice sorgente di ciascun modulo nell'output HTML. Per impostazione predefinita,
vengono generate le pagine del codice sorgente.

--include-log
Genera una pagina HTML epydoc-log.html contenente tutti i messaggi di errore e di avviso
generati da epydoc e includerli nell'output generato.

--no-include-tempo di compilazione
Non stampare il tempo di compilazione nel piè di pagina. Questo è utile se lo sei
cercando di generare build riproducibili, dove ogni build contro un dato
versione di un albero di origine produce esattamente gli stessi artefatti.

USCITA VERSIONI

-o dir, --produzione dir
La directory di output. Se dir non esiste, verrà creato. se no
viene specificata la directory di output, quindi il nome dell'azione (ad es. html or pdf). html

-c foglio, --css foglio
Foglio di stile CSS per i file di output HTML. Se foglio è un file, quindi il foglio di stile
viene copiato da quel file; altrimenti, foglio è considerato il nome di a
foglio di stile integrato. Per un elenco dei fogli di stile incorporati, esegui epidoc --Aiuto
css. Se non viene specificato un foglio di stile CSS, il foglio di stile predefinito è
Usato.

-n Nome, --nome Nome
Il nome del progetto di cui viene generata la documentazione.

-u URL, --url URL
L'URL della home page del progetto.

--link di navigazione html
Codice HTML per il collegamento alla home page nella barra di navigazione HTML. Se questo codice HTML
contiene collegamenti ipertestuali (<a href=...>), quindi verrà inserito testualmente. Se
non contiene collegamenti ipertestuali e viene specificato un URL del progetto (con
--url), quindi al collegamento viene aggiunto un collegamento ipertestuale all'URL specificato.

--file-aiuto filetto
Un file di aiuto alternativo. filetto dovrebbe contenere il corpo di un file HTML --
le barre di navigazione verranno aggiunte ad esso.

--show-frame, --no-frame
Queste opzioni controllano se l'output HTML includerà una tabella basata su frame di
pagina dei contenuti. Per impostazione predefinita, è incluso il sommario basato su frame.

--classi-separate
Nell'output di LaTeX, descrivi ogni classe in una sezione separata del
documentazione, invece di includerli nella documentazione per la loro
moduli. Questo crea un file LaTeX separato per ogni classe, quindi può anche essere
utile se vuoi includere la documentazione per una o due classi come
sezioni del tuo documento LaTeX.

GRAFICO VERSIONI

--grafico tipo di grafo
Includi grafici di tipo tipo di grafo nell'output generato. I grafici vengono generati
utilizzando l'eseguibile punto Graphviz. Se questo eseguibile non è nel percorso, allora
uso --puntopercorso per specificare la sua posizione. Questa opzione può essere ripetuta per includere
più tipi di grafici nell'output. tipo di grafo dovrebbe essere uno tra: contro tutti i,
albero di classe, callgraph, o umlclasstree.

--puntopercorso sentiero
Il percorso per il Graphviz punto eseguibile.

--font-grafico fonte
Il nome del carattere utilizzato per generare i grafici Graphviz. (ad esempio, helvetica o
volte).

--dimensione-carattere-grafico Taglia
La dimensione del carattere utilizzato per generare i grafici Graphviz, in punti.

--pstat filetto
Un file di output pstat, da utilizzare nella generazione di grafici di chiamata.

RITORNO VALORE VERSIONI

--errore in caso di errore
Restituisce uno stato di uscita diverso da zero, indicando il fallimento, se ci sono errori
incontrato.

--avviso di guasto
Restituisce uno stato di uscita diverso da zero, indicando il fallimento, eventuali errori o avvisi
vengono incontrati (esclusi gli avvisi di docstring).

--fail-on-docstring-warning
Restituisce uno stato di uscita diverso da zero, indicando il fallimento, eventuali errori o avvisi
vengono incontrati (inclusi gli avvisi di docstring).

HTML FILE

La documentazione API HTML prodotta da epidoc è costituito dai seguenti file:

OGGETTO DOCUMENTAZIONE PAGINE

index.html
Il punto di ingresso standard per la documentazione. Normalmente, index.html è una copia
del file frame (frame.html). Ma se il --no-frame viene utilizzata l'opzione, quindi
index.html è una copia della home page della documentazione API, che normalmente è la
pagina di documentazione per il pacchetto o modulo di primo livello (o la pagina degli alberi se
non esiste un pacchetto o modulo di primo livello).

modulo-modulo.html
La documentazione API per un modulo. modulo è il nome completo punteggiato del
modulo, come sys or epydoc.epytext.

classe-classe.html
La documentazione dell'API per una classe, un'eccezione o un tipo. classe è il completo?
nome della classe con punti, ad esempio epydoc.epytext.Token or matrice.Tipo di matrice.

modulo-pysrc.html
Una pagina evidenziata dalla sintassi contenente il codice sorgente Python per modulo. Questo
include collegamenti alle pagine della documentazione dell'API.

modulo-albero.html
La gerarchia dei moduli.

albero-classe.html
La gerarchia di classe. Questa pagina viene generata solo se almeno una classe è
Documentati.

INDICI

identificatore-indice.html
Un indice di tutti gli identificatori documentati. Se l'indice dell'identificatore ne contiene di più
di 3,000 voci, verrà suddivisa in pagine separate per ogni lettera,
detto identificatore-indice-a.html, identificatore-indice-b.html, ecc.

indice-termine.html
Un indice di tutti i termini di definizione esplicitamente contrassegnati. Questa pagina è solo
generato se almeno un termine di definizione è contrassegnato in una docstring formattata.

indice-bug.html
Un indice di tutti esplicitamente contrassegnati @insetto campi. Questa pagina viene generata solo se
almeno una @insetto il campo è elencato in una docstring formattata.

indice-da fare.html
Un indice di tutti esplicitamente contrassegnati @da fare campi. Questa pagina viene generata solo se
almeno una @da fare il campo è elencato in una docstring formattata.

indice-modificato.html
Un indice di tutti esplicitamente contrassegnati @cambiato campi. Questa pagina è solo generata
se almeno uno @cambiato il campo è elencato in una docstring formattata.

indice-deprecato.html
Un indice di tutti esplicitamente contrassegnati @deprecato campi. Questa pagina è solo
generato se almeno uno @deprecato il campo è elencato in una docstring formattata.

poiché-index.html
Un indice di tutti esplicitamente contrassegnati @da campi. Questa pagina è solo generata
se almeno uno @da il campo è elencato in una docstring formattata.

A BASE DI TELAI TABELLA OF INDICE

frame.html
Il file dei frame principali. Due cornici sul lato sinistro della finestra contengono a
sommario e il riquadro principale sul lato destro della finestra contiene
pagine di documentazione API.

toc.html
La pagina del sommario di primo livello. Questa pagina viene visualizzata in alto a sinistra
cornice di frame.html, e fornisce collegamenti al toc-tutto.html e
toc-modulo-modulo.html pagine.

toc-tutto.html
Il sommario dell'intero progetto. Questa pagina viene visualizzata in
cornice in basso a sinistra di frame.htmle fornisce collegamenti a ogni classe, tipo,
eccezione, funzione e variabile definite dal progetto.

toc-modulo-modulo.html
Il sommario di un modulo. Questa pagina è visualizzata in basso a sinistra
cornice di frame.htmle fornisce collegamenti a ogni classe, tipo, eccezione,
funzione e variabile definita dal modulo. modulo è il punteggiato completo
nome del modulo, ad esempio sys or epydoc.epytext.

ALTRO PAGINE

aiuto.html
La pagina di aiuto per il progetto. Questa pagina spiega come utilizzare e navigare nel
pagina web prodotta da epydoc.

reindirizzare.html
Questa pagina utilizza javascript per tradurre i nomi punteggiati nei loro corrispondenti
URL. Ad esempio, nella documentazione di epydoc, caricando la pagina
reindirizzerà automaticamente il
browser per .

epydoc.css
Il foglio di stile CSS utilizzato per visualizzare tutte le pagine HTML.

epydoc.js
Un file javascript utilizzato per definire le funzioni javascript utilizzate da epydoc.

epydoc-log.html
Una pagina contenente un registro di tutti gli avvisi e gli errori generati da
epydoc, insieme a una tabella che elenca tutte le opzioni utilizzate.

LATEX FILE

La documentazione dell'API LaTeX prodotta da epidoc è costituito dai seguenti file:

API.pdf
Un file Adobe Acrobat (pdf) contenente la documentazione API completa. Questo
il file viene generato solo se usi il --PDF opzione.

api.tex
Il file LaTeX di primo livello. Questo file importa gli altri file LaTeX, per creare un
unico documento unificato.

api.dvi
Un file dvi contenente la documentazione API completa. Questo file è solo
generato se si utilizza il --dvi opzione, il --ps opzione, o il --PDF opzione.

api.ps Un file postscript contenente la documentazione completa dell'API. Questo file è solo
generato se si utilizza il --ps opzione o il --PDF opzione.

modulo-modulo.tex
La documentazione API per un modulo. modulo è il nome completo punteggiato del
modulo, come sys or epydoc.epytext.

classe-classe.tex
La documentazione dell'API per una classe, un'eccezione o un tipo. classe è il completo?
nome della classe con punti, ad esempio epydoc.epytext.Token o array.ArrayType.
Questi file di documentazione della classe vengono creati solo se il --classi-separate
viene utilizzata l'opzione; in caso contrario, la documentazione per ogni classe è inclusa nella sua
file di documentazione del modulo.

DIAGNOSTICA

EPITESTO MARCATURA AVVERTIMENTO MESSAGGI
Gli errori epytext sono causati da docstring epytext che contengono markup non valido. Ogni volta che
viene rilevato un errore epytext, la docstring in questione viene trattata come un testo in chiaro
docstring. Epydoc può generare i seguenti errori epytext:

Piscina link bersaglio.
La destinazione specificata per la costruzione di un collegamento in linea (L{...}) non va bene-
formato. Le destinazioni del collegamento devono essere identificatori python validi.

Piscina uri bersaglio.
La destinazione specificata per una costruzione uri in linea (tu{...}) non è ben formato.
Ciò si verifica in genere se il markup in linea è annidato all'interno della destinazione URI.

campi devono obbligatoriamente: be at , il top livello.
L'elenco dei campi (@param, ecc.) è contenuto da qualche altra struttura a blocchi
(come un elenco o una sezione).

campi devono obbligatoriamente: be , il finale elementi.
L'elenco dei campi (@param, ecc.) non si trova alla fine di una docstring.

Titoli devono obbligatoriamente: verificarsi at top livello.
L'intestazione è contenuta in qualche altra struttura a blocchi (come un elenco).

Improprio dottore bloccare rientro.
Il blocco doctest dedenta oltre il rientro della sua riga di prompt iniziale.

Improprio intestazione rientro.
L'intestazione di una sezione non è allineata a sinistra con i paragrafi nel
sezione che lo contiene.

Improprio paragrafo rientro.
I paragrafi all'interno di un blocco non sono allineati a sinistra. Questo errore è spesso
generato quando le stringhe di testo in chiaro vengono analizzate utilizzando epytext.

invalido fuga.
Una sequenza di fuga sconosciuta è stata utilizzata con la costruzione di fuga in linea
(E{...}).

elenchi devono obbligatoriamente: be rientrato.
Una riga non rientrata immediatamente dopo un paragrafo inizia con un elenco puntato.
Epydoc non è sicuro se intendessi iniziare un nuovo elemento dell'elenco o se intendessi a
paragrafo per includere una parola che assomiglia a un proiettile. Se intendevi il
precedente, quindi indentare l'elenco. Se intendevi quest'ultimo, cambia il
il ritorno a capo del paragrafo o l'escape del primo carattere della parola che
sembra un proiettile.

squilibrato '{'.
La docstring contiene parentesi graffe non bilanciate. Epytext richiede che tutte le parentesi graffe
deve essere equilibrato. Per includere un singolo tutore sbilanciato, usa l'escape
sequenze E{lb} (parentesi graffa sinistra) e E{rb} (parentesi graffa destra).

squilibrato '}'.
La docstring contiene parentesi graffe non bilanciate. Epytext richiede che tutte le parentesi graffe
deve essere equilibrato. Per includere un singolo tutore sbilanciato, usa l'escape
sequenze E{lb} (parentesi graffa sinistra) e E{rb} (parentesi graffa destra).

Sconosciuto inline markup etichetta.
È stato utilizzato un tag sconosciuto con la costruzione del markup in linea ( x{...} ).

Wrong sottolineare carattere da intestazione.
Il carattere di sottolineatura utilizzato per questa intestazione di sezione non indica un
livello di sezione appropriato. Il carattere "=" dovrebbe essere usato per sottolineare
sezioni; "-" per le sottosezioni; e "~" per le sottosezioni.

Possibile mal formattato campo articolo.
Epytext ha rilevato una riga che sembra un elemento del campo, ma non è corretta
formattato. Ciò si verifica in genere quando i due punti finali (":") non sono inclusi
nell'etichetta del campo.

Possibile intestazione errore di battitura.
Epytext ha rilevato una coppia di righe che sembra un'intestazione, ma il numero di
i caratteri di sottolineatura non corrispondono al numero di caratteri nell'intestazione.
Il numero di caratteri in queste due righe deve corrispondere esattamente affinché siano
considerato un titolo.

CAMPO AVVERTENZE
Gli avvisi di campo sono causati da docstring contenenti campi non validi. Il contenuto di
i campi non validi vengono generalmente ignorati. Epydoc può generare il seguente campo
avvertenze:

@param da Sconosciuto parametro param.
È stato utilizzato un campo @param per specificare il tipo di un parametro che non lo è
incluso nella firma della funzione. Questo è in genere causato da un errore di battitura
il nome del parametro.

etichetta ha fatto non è un attenderti an discussione.
Il tag del campo etichetta è stato usato con un argomento, ma non ce ne vuole uno.

etichetta previsto an discussione.
Il tag del campo etichetta è stato usato senza un argomento, ma ne richiede uno.

@genere da Sconosciuto parametro param.
È stato utilizzato un campo @type per specificare il tipo di un parametro non incluso
nella firma della funzione. Questo è in genere causato da un errore di battitura nel
nome del parametro.

@genere da Sconosciuto variabile var.
Un campo @type è stato utilizzato per specificare il tipo di una variabile, ma nessun altro
si conoscono informazioni sulla variabile. Questo è in genere causato da un errore di battitura
il nome della variabile.

Sconosciuto campo etichetta etichetta.
Una docstring contiene un campo con il tag sconosciuto etichetta.

Ridefinizione of campo.
Più tag di campo definiscono il valore di campo nella stessa docstring, ma campo
può assumere un solo valore.

ESEMPI

epidoc -n epidoc -u http://epydoc.sf.net epidoc/
Genera la documentazione API HTML per il pacchetto epydoc e tutto il suo
sottomoduli e scrivi l'output nel html directory. Nelle intestazioni e
piè di pagina, usa epidoc come nome del progetto, e http://epydoc.sf.net come il progetto
URL.

epidoc --PDF -n epidoc epidoc/
Genera la documentazione dell'API LaTeX per il pacchetto epydoc e tutto il suo
sottomoduli e scrivi l'output nel latice directory.

EXIT STATUS

0 Esecuzione riuscita del programma.

1 Errore di utilizzo.

2 Epydoc ha generato un errore o un avviso e una delle opzioni --errore in caso di errore,
--avviso di guasto, or --fail-on-docstring-warning è stato specificato.

Altri Errore interno (eccezione Python).

Usa epydoc online usando i servizi onworks.net