epydoc - Online în cloud

PROGRAM:

NUME

epydoc - generează documentația API din documentele Python

REZUMAT

epidoc [acțiune] [Opțiuni] nume...

DESCRIERE

epidoc generează documentația API pentru modulele și pachetele Python, pe baza acestora
docstrings. Un limbaj de marcare ușor numit epitext poate fi folosit pentru formatare
docstrings și pentru a adăuga informații despre anumite câmpuri, cum ar fi parametrii și instanța
variabile. Epydoc înțelege, de asemenea, șirurile de documente scrise în ReStructuredText, Javadoc și
text simplu. În prezent, epydoc acceptă două formate de ieșire de bază: HTML și LaTeX.

Documentația HTML API produsă de epidoc constă dintr-un set de fișiere HTML, inclusiv:
o pagină de documentație API pentru fiecare clasă și modul; o pagină de cod sursă evidențiată de sintaxă
pentru fiecare modul; o pagină de index de identificare; o pagină de ajutor; și un tabel bazat pe cadre de
continuturi. Atunci când este cazul, epidoc va genera, de asemenea, pagini de index pentru bug-uri, definite
termeni și articole de făcut; o pagină de ierarhie a clasei; și o pagină de ierarhie a pachetelor.

Documentația LaTeX API produsă de epidoc constă dintr-un fișier principal LaTeX și un LaTeX
fișier pentru fiecare modul. Dacă utilizați --dvi, --ps, --pdf , apoi epidoc va invoca extern
comenzi pentru a converti ieșirea LaTeX în formatul solicitat. Rețineți că fișierele LaTeX
care conțin documentația pentru module individuale pot fi incluse sub formă de capitole sau
secțiuni ale altor documente LaTeX, folosind LaTeX \include comanda. Dacă vrei
includeți clase individuale în alte documente LaTeX, apoi utilizați --clase-separate
opțiunea de a produce un fișier LaTeX separat pentru fiecare clasă.

epidoc poate fi folosit și pentru a verifica caracterul complet al documentației API. În mod implicit,
se verifică dacă fiecare pachet public, modul, clasă, metodă și funcție are un docstring
Descriere. --teste opțiunea poate fi utilizată pentru a specifica teste suplimentare de efectuat.

REPRODUCIBILE CONSTRUIESTE COMPORTAMENT

Utilizarea datei curente în documentația generată de Epydoc are ca rezultat documentarea care
este „nereproducibil”, ceea ce înseamnă că conținutul fișierelor se modifică de la o versiune la alta
chiar dacă arborele sursă nu. Pentru a facilita generarea de versiuni reproductibile, aceasta
versiunea de Epydoc acceptă două caracteristici: --no-include-build-time și opțiunea
SOURCE_DATE_EPOCH variabilă de mediu.

--no-include-build-time opțiunea poate fi utilizată atunci când știți de la început că nu aveți nevoie
construiți marcaje temporale în documentația generată. The SOURCE_DATE_EPOCH mediu inconjurator
variabila este destinată utilizării de către sistemele de ambalare, cum ar fi procesul de construire Debian.
Se vor instala sistemele de ambalare SOURCE_DATE_EPOCH la un marcaj temporal sensibil care este cumva
legat de starea arborelui sursă, iar marca temporală va fi folosită mai degrabă de Eypdoc
decât marca temporală actuală. Construiește folosind SOURCE_DATE_EPOCH va fi astfel reproductibilă.

OPŢIUNI

Opțiunile Epydoc sunt împărțite în șase categorii: opțiuni de bază, acțiuni, generare
opțiuni, opțiuni de ieșire, opțiuni de grafic și opțiuni de valoare returnată.

BASIC OPŢIUNI

nume...
Lista obiectelor care ar trebui documentate. Obiectele pot fi specificate folosind
Nume punctate Python (cum ar fi os.cale), nume de fișiere (cum ar fi epydoc/epytext.py),
sau nume de directoare (cum ar fi epidoc/). Numele directoarelor specifică pachete și
sunt extinse pentru a include toate submodulele și sub-pachetele. Dacă vrei
excludeți anumite sub-module sau sub-pachete, utilizați --exclude opțiune
(descris mai jos).

--config fişier
Un fișier de configurare, specificând suplimentar Opțiunişi / saunume. Această opțiune
poate fi repetat.

--q, --Liniște, --v, --verbos
Produce o ieșire destul de (sau verbosă). Dacă este folosită de mai multe ori, această opțiune
produce succesiv ieșiri mai silentioase (sau verbose).

--depanare
Afișați urmărirea completă pentru erorile interne.

--termen-simplu
Nu încercați să utilizați controlul culorii sau al cursorului când afișați bara de progres,
avertismente sau erori.

ACȚIUNI

--html Scrie ieșire HTML. [Mod implicit]

--latex Scrie ieșire LaTeX.

--dvi Scrie ieșire DVI.

--ps Scrieți rezultatul Postscript.

--pdf Scrieți rezultatul Adobe Acrobat (pdf).

--Verifica Efectuați verificări de integralitate a documentației.

--murătură Scrieți documentația într-un fișier murat.

GENERAREA OPŢIUNI

--docformat format
Setați valoarea implicită pentru __docformat__ la format. __docformat__ este un modul
variabilă care specifică limbajul de marcare pentru documentele dintr-un modul.
Valoarea sa constă din numele unui limbaj de marcare, urmat opțional de a
cod de limbă (cum ar fi en pentru engleză). Pentru o listă a limbajelor de marcare
recunoscut în prezent de epydoc, rulați epidoc --Ajutor docformat.

--parse-only
Adunați toate informațiile despre obiectele documentate prin analizarea celor relevante
Cod sursă Python; în special, face nu folosește introspecția pentru a aduna
informații despre obiectele documentate. Această opțiune ar trebui utilizată atunci când
epydoc este rulat pe cod care nu este de încredere; sau pe cod care nu poate fi introspectat
din cauza dependențelor lipsă sau pentru că importarea acestuia ar provoca nedorite
efecte secundare.

--doar introspectie
Adună toate informațiile despre obiectele documentate prin introspecție; în
special, face nu adunați informații prin analizarea sursei Python a obiectului
cod.

--exclude MODEL
Nu documentați niciun obiect al cărui nume se potrivește cu expresia regulată dată
model.

--exclude-introspect MODEL
Nu folosiți introspecția pentru a aduna informații despre orice obiect al cărui nume
se potrivește cu expresia regulată dată.

--exclude-parse MODEL
Nu utilizați analiza codului sursă Python pentru a aduna informații despre orice obiect
al cărui nume se potrivește cu expresia regulată dată.

--moştenire format
Formatul care ar trebui utilizat pentru a afișa metodele, variabilele și
proprietățile din tabelele „rezumate” generate. Dacă format este „grupat”, atunci
obiectele moștenite sunt adunate în grupuri, în funcție de clasa în care se află
moștenit de la. Dacă format este „listat”, apoi obiectele moștenite sunt listate în a
lista scurtă de la sfârșitul tabelului rezumativ. Dacă format este „inclus”, atunci
obiectele moștenite sunt amestecate cu obiecte nemoștenite. Formatul implicit
pentru ieşirea HTML este „grupată”.

--arata-privat, --nu-privat
Aceste opțiuni controlează dacă documentația este generată pentru obiectele private.
În mod implicit, documentația generată include obiecte private, iar utilizatorii pot
alegeți dacă doriți să vizualizați sau nu obiectele private, făcând clic pe „afișați privat”
și „ascundeți linkurile private”. Dar dacă doriți să descurajați utilizatorii de la direct
accesând obiecte private, atunci este posibil să preferați să nu generați documentație
pentru obiecte private.

--arata-importurile, --fara-importuri
Aceste opțiuni controlează dacă importurile de module sunt incluse în formatul generat
documentație. În mod implicit, importurile nu sunt incluse.

--show-sourcecode, --fără cod sursă
Aceste opțiuni controlează dacă epydoc ar trebui să genereze sau nu evidențiate de sintaxă
pagini care conțin codul sursă al fiecărui modul din ieșirea HTML. În mod implicit,
sunt generate paginile de cod sursă.

--include-log
Generați o pagină HTML epidoc-log.html conţinând toate mesajele de eroare şi de avertizare
care sunt generate de epydoc și includeți-l în rezultatul generat.

--no-include-build-time
Nu tipăriți timpul de construcție în subsolul paginii. Acest lucru este util dacă sunteți
încercând să genereze versiuni reproductibile, în care fiecare construiește împotriva unui anumit
versiunea unui arbore sursă produce exact aceleași artefacte.

REZULTATE OPŢIUNI

-o dir, --ieșire dir
Directorul de ieșire. Dacă dir nu există, atunci va fi creat. Daca nu
directorul de ieșire este specificat, apoi numele acțiunii (de exemplu, html or pdf). html

-c coală, --css coală
Foaia de stil CSS pentru fișierele de ieșire HTML. Dacă coală este un fișier, apoi foaia de stil
este copiat din acel fișier; in caz contrar, coală este considerat numele unui
foaie de stil încorporată. Pentru o listă a foilor de stil încorporate, rulați epidoc --Ajutor
CSS. Dacă nu este specificată o foaie de stil CSS, atunci foaia de stil implicită este
folosit.

-n nume, --Nume nume
Numele proiectului a cărui documentație este generată.

-u url, --url url
Adresa URL a paginii de start a proiectului.

--navlink html
Cod HTML pentru linkul paginii de pornire din bara de navigare HTML. Dacă acest cod HTML
conține orice hyperlink (<a href=...>), apoi va fi introdus literal. Dacă
nu conține niciun hyperlink și este specificată o adresă URL a proiectului (cu
--url), apoi un hyperlink către adresa URL specificată este adăugat la link.

--help-file fişier
Un fișier de ajutor alternativ. fişier ar trebui să conțină corpul unui fișier HTML --
i se vor adăuga bare de navigare.

--show-frames, --fara-cadre
Aceste opțiuni controlează dacă ieșirea HMTL va include un tabel bazat pe cadre de
cuprins. În mod implicit, cuprinsul bazat pe cadre este inclus.

--clase-separate
În rezultatul LaTeX, descrieți fiecare clasă într-o secțiune separată a
documentație, în loc să le includă în documentația pentru lor
module. Acest lucru creează un fișier LaTeX separat pentru fiecare clasă, așa că poate fi și el
util dacă doriți să includeți documentația pentru una sau două clase ca
secțiuni ale propriului document LaTeX.

GRAFIC OPŢIUNI

--grafic tip grafic
Includeți grafice de tip tip grafic în ieșirea generată. Sunt generate grafice
folosind executabilul punct Graphviz. Dacă acest executabil nu este pe cale, atunci
utilizare --dotpath pentru a-i preciza locația. Această opțiune poate fi repetată pentru a include
mai multe tipuri de grafice în ieșire. tip grafic ar trebui să fie unul dintre: toate,
arborele de clasă, callgraph, umlclasstree.

--dotpath cale
Calea către Graphviz punct executabil.

--graf-font font
Numele fontului folosit pentru a genera grafice Graphviz. (de exemplu, helvetica sau
ori).

--graph-font-size mărimea
Dimensiunea fontului folosit pentru a genera grafice Graphviz, în puncte.

--pstat fişier
Un fișier de ieșire pstat, pentru a fi utilizat la generarea graficelor de apel.

A REVENI VALUE OPŢIUNI

--fail-on-error
Returnează o stare de ieșire diferită de zero, indicând eșecul, dacă există erori
întâlnite.

--fail-on-warning
Returnează o stare de ieșire diferită de zero, indicând eșec, dacă există erori sau avertismente
sunt întâlnite (nu includ avertismentele documentare).

--fail-on-docstring-warning
Returnează o stare de ieșire diferită de zero, indicând eșec, dacă există erori sau avertismente
sunt întâlnite (inclusiv avertismente docstring).

HTML DOSARE

Documentația HTML API produsă de epidoc constă din următoarele fișiere:

OBIECT DOCUMENTAȚIE PAGINI

index.html
Punctul de intrare standard pentru documentație. În mod normal, index.html este o copie
a fișierului cadre (cadre.html). Dar dacă --fara-cadre atunci este folosită opțiunea
index.html este o copie a paginii de pornire a documentației API, care este în mod normal
pagina de documentație pentru pachetul sau modulul de nivel superior (sau pagina de arbori dacă
nu există pachet sau modul de nivel superior).

modul-module.html
Documentația API pentru un modul. modul este numele complet punctat al
modul, cum ar fi SYS or epydoc.epytext.

clasă-class.html
Documentația API pentru o clasă, o excepție sau un tip. clasă este complet
numele punctat al clasei, cum ar fi epydoc.epytext.Token or array.ArrayType.

modul-pysrc.html
O pagină evidențiată de sintaxă care conține codul sursă Python pentru modul. Acest
pagina include linkuri către paginile de documentație API.

module-tree.html
Ierarhia modulelor.

class-tree.html
Ierarhia clasei. Această pagină este generată numai dacă există cel puțin o clasă
documentate.

INDICII

identificator-index.html
Un index al tuturor identificatorilor documentați. Dacă indexul de identificare conține mai multe
mai mult de 3,000 de intrări, apoi va fi împărțit în pagini separate pentru fiecare literă,
numit identificator-index-a.html, identificator-index-b.html, Etc

termen-index.html
Un index al tuturor termenilor definitori marcați în mod explicit. Această pagină este doar
generat dacă cel puțin un termen de definiție este marcat într-un șir documentar formatat.

bug-index.html
Un index al tuturor marcate în mod explicit @gândac câmpuri. Această pagină este generată numai dacă
cel puțin unul @gândac câmpul este listat într-un șir de documente formatat.

todo-index.html
Un index al tuturor marcate în mod explicit @a face câmpuri. Această pagină este generată numai dacă
cel puțin unul @a face câmpul este listat într-un șir de documente formatat.

changed-index.html
Un index al tuturor marcate în mod explicit @schimbat câmpuri. Această pagină este doar generată
dacă măcar unul @schimbat câmpul este listat într-un șir de documente formatat.

deprecated-index.html
Un index al tuturor marcate în mod explicit @depreciat câmpuri. Această pagină este doar
generat dacă cel puțin unul @depreciat câmpul este listat într-un șir de documente formatat.

din moment ce-index.html
Un index al tuturor marcate în mod explicit @de cand câmpuri. Această pagină este doar generată
dacă măcar unul @de cand câmpul este listat într-un șir de documente formatat.

BAZATE PE CADRE TABEL OF CUPRINS

cadre.html
Fișierul de cadre principale. Două rame din partea stângă a ferestrei conțin a
cuprins și cadrul principal din partea dreaptă a ferestrei conține
Pagini de documentație API.

toc.html
Pagina de cuprins de nivel superior. Această pagină este afișată în stânga sus
cadru de cadre.html, și oferă link-uri către toc-totul.html și
toc-modul-module.html pagini.

toc-totul.html
Cuprinsul întregului proiect. Această pagină este afișată în
cadru din stânga jos al cadre.htmlși oferă link-uri către fiecare clasă, tip,
excepție, funcție și variabilă definite de proiect.

toc-modul-module.html
Cuprinsul unui modul. Această pagină este afișată în stânga jos
cadru de cadre.htmlși oferă link-uri către fiecare clasă, tip, excepție,
funcția și variabila definită de modul. modul este complet punctat
numele modulului, cum ar fi SYS or epydoc.epytext.

ALTE PAGINI

ajutor.html
Pagina de ajutor pentru proiect. Această pagină explică cum să utilizați și să navigați în
pagină web produsă de epydoc.

redirect.html
Această pagină folosește javascript pentru a traduce numele punctate în corespunzătoare lor
URL-uri. De exemplu, în documentația epydoc, încărcarea paginii
va redirecționa automat
browser la .

epydoc.css
Foaia de stil CSS folosită pentru a afișa toate paginile HTML.

epydoc.js
Un fișier javascript folosit pentru a defini funcțiile javascript utilizate de epydoc.

epidoc-log.html
O pagină care conține un jurnal al tuturor avertismentelor și erorilor care au fost generate de
epydoc, împreună cu un tabel care listează toate opțiunile care au fost utilizate.

TÎRZIU DOSARE

Documentația LaTeX API produsă de epidoc constă din următoarele fișiere:

api.pdf
Un fișier Adobe Acrobat (pdf) care conține documentația completă API. Acest
fișierul este generat numai dacă utilizați --pdf opțiune.

api.tex
Fișierul LaTeX de nivel superior. Acest fișier importă celelalte fișiere LaTeX, pentru a crea un
document unic unic.

api.dvi
Un fișier dvi care conține documentația completă API. Acest fișier este doar
generat dacă utilizați --dvi opțiune, --ps sau opțiunea --pdf opțiune.

api.ps Un fișier postscript care conține documentația completă API. Acest fișier este doar
generat dacă utilizați --ps sau opțiunea --pdf opțiune.

modul-modul.tex
Documentația API pentru un modul. modul este numele complet punctat al
modul, cum ar fi SYS or epydoc.epytext.

clasă-clasa.tex
Documentația API pentru o clasă, o excepție sau un tip. clasă este complet
numele punctat al clasei, cum ar fi epydoc.epytext.Token sau array.ArrayType.
Aceste fișiere de documentație de clasă sunt create numai dacă --clase-separate
este utilizată opțiunea; în caz contrar, documentația pentru fiecare clasă este inclusă în ea
dosarul de documentație al modulului.

DIAGNOSTIC

EPYTEXT MARKUP AVERTISMENT MESAJE
Erorile Epytext sunt cauzate de șiruri de documente Epytext care conțin markup nevalid. Oricând
este detectată o eroare epytext, șirul document în cauză este tratat ca text simplu
docstring. Epydoc poate genera următoarele erori epytext:

Rău legătură țintă.
Ținta specificată pentru o construcție de link inline (L{...}) nu este bine-
format. Țintele linkurilor trebuie să fie identificatori Python validi.

Rău uri țintă.
Ținta specificată pentru o construcție uri inline (U{...}) nu este bine format.
Acest lucru se întâmplă de obicei dacă marcajul inline este imbricat în interiorul țintei URI.

Domenii trebuie să: be at il top nivel.
Lista câmpurilor (@param, etc.) este conținut de o altă structură de bloc
(cum ar fi o listă sau o secțiune).

Domenii trebuie să: be il final elemente.
Lista câmpurilor (@param, etc.) nu se află la sfârșitul unui șir documentar.

Rubrici trebuie să: avea loc at top nivel.
Titlul este inclus într-o altă structură de bloc (cum ar fi o listă).

impropriu doctest bloca indentare.
Blocul doctest se dedentează dincolo de indentarea liniei inițiale de prompt.

impropriu îndreptare indentare.
Titlul unei secțiuni nu este aliniat la stânga cu paragrafele din
secțiunea care o conține.

impropriu paragraf indentare.
Paragrafele dintr-un bloc nu sunt aliniate la stânga. Această eroare este adesea
generat atunci când șirurile documentare de text simplu sunt analizate folosind epytext.

Invalid evadare.
O secvență de evadare necunoscută a fost utilizată cu construcția de evacuare în linie
(E{...}).

liste trebuie să: be indentat.
O linie neindensată imediat după un paragraf începe cu un marcator de listă.
Epydoc nu este sigur dacă ați intenționat să începeți un nou articol din listă sau dacă ați vrut să începeți
paragraf pentru a include un cuvânt care arată ca un glonț. Dacă ai intenționat ca
fost, apoi indentează lista. Dacă ați intenționat aceasta din urmă, atunci schimbați
împachetarea paragrafului sau evadarea primului caracter al cuvântului care
arată ca un glonț.

Dezechilibrat „{”.
Documentul conține bretele dezechilibrate. Epytext necesită ca toate acoladele
trebuie să fie echilibrat. Pentru a include o singură bretele dezechilibrate, utilizați evadarea
secvențele E{lb} (acolada din stânga) și E{rb} (acolada din dreapta).

Dezechilibrat „}”.
Documentul conține bretele dezechilibrate. Epytext necesită ca toate acoladele
trebuie să fie echilibrat. Pentru a include o singură bretele dezechilibrate, utilizați evadarea
secvențele E{lb} (acolada din stânga) și E{rb} (acolada din dreapta).

Necunoscut inline marcare etichetă.
O etichetă necunoscută a fost folosită cu construcția de marcare inline ( x{...} ).

Greșit sublinia caracter pentru poziția.
Caracterul de subliniere folosit pentru acest titlu de secțiune nu indică un
nivelul de secție corespunzător. Caracterul „=" ar trebui folosit pentru a sublinia
secțiuni; „-” pentru subsecțiuni; și „~” pentru subsubsecțiuni.

Posibil mal-formatat camp articol.
Epytext a detectat o linie care arată ca un element de câmp, dar nu este corect
formatat. Acest lucru se întâmplă de obicei atunci când două puncte (":") nu sunt incluse
în eticheta de câmp.

Posibil îndreptare greșeală de scriere.
Epytext a detectat o pereche de linii care arată ca un titlu, dar numărul de
caracterele de subliniere nu se potrivesc cu numărul de caractere din titlu.
Numărul de caractere din aceste două rânduri trebuie să se potrivească exact pentru ca ele să fie
considerat un titlu.

CAMP AVERTISMENTE
Avertismentele de câmp sunt cauzate de șiruri de documente care conțin câmpuri nevalide. Conținutul de
câmpurile nevalide sunt în general ignorate. Epydoc poate genera următorul câmp
Avertizări:

@param pentru necunoscut parametru PARAM.
Un câmp @param a fost folosit pentru a specifica tipul unui parametru care nu este
incluse în semnătura funcției. Acest lucru este cauzat de obicei de o greșeală de scriere
numele parametrului.

etichetă a făcut nu aștepta an a susținut.
Eticheta de câmp etichetă a fost folosit cu un argument, dar nu este nevoie de unul.

etichetă de aşteptat an a susținut.
Eticheta de câmp etichetă a fost folosit fără argument, dar necesită unul.

@tip pentru necunoscut parametru PARAM.
Un câmp @type a fost folosit pentru a specifica tipul unui parametru care nu este inclus
în semnătura funcției. Acest lucru este cauzat de obicei de o greșeală de scriere în fișierul
numele parametrului.

@tip pentru necunoscut variabil a fost.
Un câmp @type a fost folosit pentru a specifica tipul unei variabile, dar nu alta
se cunosc informații despre variabilă. Acest lucru este cauzat de obicei de o greșeală de scriere
numele variabilei.

Necunoscut camp etichetă etichetă.
Un docstring conține un câmp cu eticheta necunoscută etichetă.

Redefinirea of camp.
Mai multe etichete de câmp definesc valoarea lui camp în același docstring, dar camp
poate lua doar o singură valoare.

EXEMPLE

epidoc -n epidoc -u http://epydoc.sf.net epidoc/
Generați documentația HTML API pentru pachetul epydoc și toate acestea
submodule și scrieți rezultatul în html director. În anteturi și
subsoluri, folosiți epidoc ca numele proiectului și http://epydoc.sf.net ca proiect
URL.

epidoc --pdf -n epidoc epidoc/
Generați documentația LaTeX API pentru pachetul epydoc și tot
submodule și scrieți rezultatul în latex director.

EXIT STAREA

0 Execuție cu succes a programului.

1 Eroare de utilizare.

2 Epydoc a generat o eroare sau un avertisment și una dintre opțiuni --fail-on-error,
--fail-on-warning, or --fail-on-docstring-warning a fost specificat.

alte Eroare internă (excepție Python).

Utilizați epydoc online folosind serviciile onworks.net