epydoc - En ligne dans le Cloud

PROGRAMME:

Nom

epydoc - générer de la documentation API à partir des docstrings Python

SYNOPSIS

épidoc [action] [Options] noms...

DESCRIPTION

épidoc génère une documentation API pour les modules et packages Python, en fonction de leur
docstrings. Un langage de balisage léger appelé épytexte peut être utilisé pour formater
docstrings, et pour ajouter des informations sur des champs spécifiques, tels que les paramètres et l'instance
variables. Epydoc comprend également les docstrings écrites en ReStructuredText, Javadoc et
texte en clair. Actuellement, epydoc prend en charge deux formats de sortie de base : HTML et LaTeX.

La documentation de l'API HTML produite par épidoc se compose d'un ensemble de fichiers HTML, comprenant :
une page de documentation API pour chaque classe et module ; une page de code source avec mise en évidence de la syntaxe
pour chaque module ; une page d'index des identifiants ; une page d'aide ; et un tableau basé sur des cadres de
Contenu. Le cas échéant, épidoc générera également des pages d'index pour les bogues, définis
termes et tâches à effectuer ; une page de hiérarchie de classe ; et une page de hiérarchie des packages.

La documentation de l'API LaTeX produite par épidoc se compose d'un fichier LaTeX principal et d'un fichier LaTeX
fichier pour chaque module. Si tu utilises --dvi, --PS, ou --pdf , puis épidoc invoquera externe
commandes pour convertir la sortie LaTeX au format demandé. Notez que les fichiers LaTeX
contenant la documentation des modules individuels peuvent être inclus sous forme de chapitres ou
sections d'autres documents LaTeX, en utilisant le LaTeX \comprendre commander. Si vous souhaitez
inclure des classes individuelles dans d'autres documents LaTeX, puis utiliser le --classes-separes
option pour produire un fichier LaTeX séparé pour chaque classe.

épidoc peut également être utilisé pour vérifier l'exhaustivité de la documentation de l'API. Par défaut,
il vérifie que chaque package public, module, classe, méthode et fonction a une docstring
la description. le --tests L'option peut être utilisée pour spécifier des tests supplémentaires à effectuer.

REPRODUCTIBLE CONSTRUIRE COMPORTEMENT

L'utilisation de la date actuelle dans la documentation générée par Epydoc permet d'obtenir une documentation qui
est « non reproductible », ce qui signifie que le contenu des fichiers change d'une version à l'autre
même si l'arborescence source ne le fait pas. Pour faciliter la génération de builds reproductibles, cette
version d'Epydoc prend en charge deux fonctionnalités : --no-include-build-time option et le
SOURCE_DATE_EPOCH variable d'environnement.

Le manuel de formation --no-include-build-time L'option peut être utilisée lorsque vous savez d'avance que vous n'avez pas besoin
construire des horodatages dans votre documentation générée. Les SOURCE_DATE_EPOCH convivial
La variable est destinée à être utilisée par les systèmes d'empaquetage, tels que le processus de construction Debian.
Les systèmes d'emballage définiront SOURCE_DATE_EPOCH à un horodatage raisonnable qui est en quelque sorte
lié à l'état de l'arbre source, et cet horodatage sera utilisé par Eypdoc plutôt
que l'horodatage actuel. Construit en utilisant SOURCE_DATE_EPOCH sera ainsi reproductible.

OPTIONS

Les options d'Epydoc sont divisées en six catégories : options de base, actions, génération
options, options de sortie, options de graphique et options de valeur de retour.

BASIQUE OPTIONS

noms...
La liste des objets qui doivent être documentés. Les objets peuvent être spécifiés en utilisant
Les noms pointillés Python (tels que chemin.os), les noms de fichiers (tels que epydoc/epytext.py),
ou des noms de répertoires (tels que épydoc/). Les noms de répertoire spécifient les packages, et
sont étendus pour inclure tous les sous-modules et sous-packages. Si vous souhaitez
exclure certains sous-modules ou sous-packages, utilisez le --exclure option
(décrit ci-dessous).

--config filet
Un fichier de configuration, spécifiant des Optionset/ounoms. Cette option
peut être répété.

--q, --calmer, --v, --verbeux
Produisez une sortie assez (ou verbeuse). Si elle est utilisée plusieurs fois, cette option
produit successivement une sortie plus silencieuse (ou verbeuse).

--déboguer
Afficher les traçabilités complètes pour les erreurs internes.

--simple-terme
N'essayez pas d'utiliser la couleur ou le contrôle du curseur lors de l'affichage de la barre de progression,
avertissements ou erreurs.

ACTIONS

--html Écrire une sortie HTML. [défaut]

--latex Écrire la sortie LaTeX.

--dvi Écrire la sortie DVI.

--PS Écrire une sortie Postscript.

--pdf Écrire une sortie Adobe Acrobat (pdf).

--Chèque Effectuer des contrôles d'exhaustivité sur la documentation.

--cornichon Écrivez la documentation dans un fichier pickle.

GÉNÉRATION OPTIONS

--docformat le format
Définir la valeur par défaut pour __docformat__ à le format. __docformat__ est un module
variable qui spécifie le langage de balisage pour les docstrings dans un module.
Sa valeur est constituée du nom d'un langage de balisage, éventuellement suivi d'un
code de langue (comme en pour l'anglais). Pour une liste des langages de balisage
actuellement reconnu par epydoc, exécutez épidoc --Aidez-moi format de doc.

--parse uniquement
Rassemblez toutes les informations sur les objets documentés en analysant les
code source Python ; en particulier, faire pas utiliser l'introspection pour recueillir
informations sur les objets documentés. Cette option doit être utilisée lorsque
epydoc est exécuté sur du code non fiable ; ou sur du code qui ne peut pas être introspecté
à cause de dépendances manquantes, ou parce que l'importer entraînerait des
Effets secondaires.

--introspection uniquement
Recueillir toutes les informations sur les objets documentés par introspection ; dans
particulier, faire pas recueillir des informations en analysant la source Python de l'objet
code.

--exclure RECONNAISSANCE
Ne documenter aucun objet dont le nom correspond à l'expression régulière donnée
motif.

--exclude-introspection RECONNAISSANCE
N'utilisez pas l'introspection pour recueillir des informations sur un objet dont le nom
correspond à l'expression régulière donnée.

--exclude-analyse RECONNAISSANCE
N'utilisez pas l'analyse du code source Python pour collecter des informations sur un objet
dont le nom correspond à l'expression régulière donnée.

--héritage le format
Le format qui doit être utilisé pour afficher les méthodes, variables et
propriétés dans les tableaux "résumés" générés. Si le format est "groupé", alors
les objets hérités sont regroupés en groupes, en fonction de la classe à laquelle ils appartiennent
hérité de. Si le format est « listé », alors les objets hérités sont répertoriés dans un
courte liste à la fin du tableau récapitulatif. Si le format est « inclus », alors
les objets hérités sont mélangés avec des objets non hérités. Le format par défaut
pour la sortie HTML est "groupé".

--show-privé, --non-privé
Ces options contrôlent si la documentation est générée pour les objets privés.
Par défaut, la documentation générée comprend des objets privés et les utilisateurs peuvent
choisir d'afficher ou non les objets privés, en cliquant sur "afficher privé"
et « masquer les liens privés ». Mais si vous voulez décourager les utilisateurs de
accéder à des objets privés, vous préférerez peut-être ne pas générer de documentation
pour les objets privés.

--show-importations, --no-importations
Ces options contrôlent si les importations de modules sont incluses dans le fichier généré.
Documentation. Par défaut, les importations ne sont pas incluses.

--show-code source, --no-code source
Ces options contrôlent si epydoc doit générer ou non la syntaxe en surbrillance
pages contenant le code source de chaque module dans la sortie HTML. Par défaut,
les pages de code source sont générées.

--include-journal
Générer une page HTML epydoc-log.html contenant tous les messages d'erreur et d'avertissement
qui sont générés par epydoc, et l'inclure dans la sortie générée.

--no-include-build-time
N'imprimez pas le temps de construction dans le pied de page. Ceci est utile si vous êtes
essayer de générer des builds reproductibles, où chaque build contre un donné
version d'une arborescence source produit exactement les mêmes artefacts.

SORTIE OPTIONS

-o dir, --output dir
Le répertoire de sortie. Si dir n'existe pas, alors il sera créé. Sinon
le répertoire de sortie est spécifié, puis le nom de l'action (par exemple, html or pdf). html

-c feuille, --css feuille
Feuille de style CSS pour les fichiers de sortie HTML. Si feuille est un fichier, puis la feuille de style
est copié à partir de ce fichier ; autrement, feuille est considéré comme le nom d'un
feuille de style intégrée. Pour obtenir la liste des feuilles de style intégrées, exécutez épidoc --Aidez-moi
css. Si aucune feuille de style CSS n'est spécifiée, la feuille de style par défaut est
utilisé.

-n prénom, --Nom prénom
Le nom du projet dont la documentation est générée.

-u url, --url url
L'URL de la page d'accueil du projet.

--navlink html
Code HTML pour le lien de la page d'accueil dans la barre de navigation HTML. Si ce code HTML
contient des hyperliens (<a href=...>), alors il sera inséré mot à mot. Si
il ne contient aucun lien hypertexte et une URL de projet est spécifiée (avec
--url), puis un lien hypertexte vers l'URL spécifiée est ajouté au lien.

--fichier d'aide filet
Un autre fichier d'aide. filet doit contenir le corps d'un fichier HTML --
des barres de navigation y seront ajoutées.

--show-frames, --pas de cadres
Ces options contrôlent si la sortie HMTL inclura un tableau basé sur des trames de
page de contenu. Par défaut, la table des matières basée sur des cadres est incluse.

--classes-separes
Dans la sortie LaTeX, décrivez chaque classe dans une section distincte du
documentation, au lieu de les inclure dans la documentation de leur
modules. Cela crée un fichier LaTeX distinct pour chaque classe, il peut donc également être
utile si vous souhaitez inclure la documentation pour une ou deux classes comme
sections de votre propre document LaTeX.

GRAPHIQUE OPTIONS

--graphique type de graphique
Inclure des graphiques de type type de graphique dans la sortie générée. Les graphiques sont générés
en utilisant l'exécutable Graphviz dot. Si cet exécutable n'est pas sur le chemin, alors
utilisé --dotpath pour préciser son emplacement. Cette option peut être répétée pour inclure
plusieurs types de graphiques dans la sortie. type de graphique devrait être l'un des : tous,
arbre de classe, graphe d'appel, ou umlclasstree.

--dotpath chemin
Le chemin vers le Graphviz point exécutable

--graph-police fonte
Le nom de la police utilisée pour générer des graphiques Graphviz. (par exemple, helvetica ou
fois).

--graph-font-size longueur du câble
La taille de la police utilisée pour générer des graphiques Graphviz, en points.

--pstat filet
Un fichier de sortie pstat, à utiliser pour générer des graphiques d'appels.

RETOUR VALEURE OPTIONS

--échec sur erreur
Renvoie un état de sortie différent de zéro, indiquant l'échec, si des erreurs sont
rencontré.

--échec sur avertissement
Renvoie un état de sortie différent de zéro, indiquant l'échec, en cas d'erreurs ou d'avertissements
sont rencontrés (sans compter les avertissements docstring).

--fail-on-docstring-avertissement
Renvoie un état de sortie différent de zéro, indiquant l'échec, en cas d'erreurs ou d'avertissements
sont rencontrés (y compris les avertissements docstring).

HTML DES DOSSIERS

La documentation de l'API HTML produite par épidoc se compose des fichiers suivants :

OBJET DOCUMENTATION PAGES

index.html
Le point d'entrée standard pour la documentation. Normalement, index.html est une copie
du fichier de cadres (cadres.html). Mais si le --pas de cadres l'option est utilisée, alors
index.html est une copie de la page d'accueil de la documentation de l'API, qui est normalement la
la page de documentation du package ou module de niveau supérieur (ou la page des arborescences si
il n'y a pas de package ou de module de niveau supérieur).

module-module.html
La documentation de l'API pour un module. module est le nom complet en pointillé du
modules, tels que sys or epydoc.epytext.

classe-classe.html
La documentation de l'API pour une classe, une exception ou un type. classe est le complet
nom en pointillé de la classe, comme epydoc.epytext.Token or tableau.ArrayType.

module-pysrc.html
Une page en surbrillance syntaxique contenant le code source Python pour module
La page comprend des liens vers les pages de documentation de l'API.

arbre-module.html
La hiérarchie des modules.

arbre-classe.html
La hiérarchie des classes. Cette page n'est générée que si au moins une classe est
documenté.

INDICES

identificateur-index.html
Un index de tous les identifiants documentés. Si l'index de l'identifiant contient plus
plus de 3,000 XNUMX entrées, il sera ensuite divisé en pages distinctes pour chaque lettre,
nommé identifiant-index-a.html, identifiant-index-b.html, etc.

index-terme.html
Un index de tous les termes de définition explicitement marqués. Cette page est seulement
généré si au moins un terme de définition est marqué dans une chaîne de documentation formatée.

index-bug.html
Un index de tous explicitement marqués @bogue des champs. Cette page n'est générée que si
au moins un @bogue Le champ est répertorié dans une docstring formatée.

todo-index.html
Un index de tous explicitement marqués @à faire des champs. Cette page n'est générée que si
au moins un @à faire Le champ est répertorié dans une docstring formatée.

index-modifié.html
Un index de tous explicitement marqués @modifié des champs. Cette page est uniquement générée
si au moins un @modifié Le champ est répertorié dans une docstring formatée.

index-déprécié.html
Un index de tous explicitement marqués @obsolète des champs. Cette page est seulement
généré si au moins un @obsolète Le champ est répertorié dans une docstring formatée.

depuis-index.html
Un index de tous explicitement marqués @puisque des champs. Cette page est uniquement générée
si au moins un @puisque Le champ est répertorié dans une docstring formatée.

BASÉ SUR LES CADRES TABLE OF CONTENU

cadres.html
Le fichier des cadres principaux. Deux cadres sur le côté gauche de la fenêtre contiennent un
table des matières, et le cadre principal sur le côté droit de la fenêtre contient
Pages de documentation de l'API.

toc.html
La page de table des matières de niveau supérieur. Cette page est affichée en haut à gauche
cadre de cadres.html, et fournit des liens vers le toc-tout.html et
toc-module-module.html .

toc-tout.html
La table des matières pour l'ensemble du projet. Cette page s'affiche dans le
cadre inférieur gauche de cadres.html, et fournit des liens vers chaque classe, type,
exception, fonction et variable définies par le projet.

toc-module-module.html
La table des matières d'un module. Cette page est affichée en bas à gauche
cadre de cadres.html, et fournit des liens vers chaque classe, type, exception,
fonction et variable définie par le module. module est le pointillé complet
nom du module, comme sys or epydoc.epytext.

AUTRES PAGES

aide.html
La page d'aide du projet. Cette page explique comment utiliser et naviguer dans le
page web produite par epydoc.

rediriger.html
Cette page utilise javascript pour traduire les noms pointés en leur correspondant
URL. Par exemple, dans la documentation d'epydoc, le chargement de la page
redirigera automatiquement le
navigateur vers .

épydoc.css
La feuille de style CSS utilisée pour afficher toutes les pages HTML.

epydoc.js
Un fichier javascript utilisé pour définir les fonctions javascript utilisées par epydoc.

epydoc-log.html
Une page contenant un journal de tous les avertissements et erreurs générés par
epydoc, ainsi qu'un tableau répertoriant toutes les options utilisées.

LATEX DES DOSSIERS

La documentation de l'API LaTeX produite par épidoc se compose des fichiers suivants :

api.pdf
Un fichier Adobe Acrobat (pdf) contenant la documentation complète de l'API. Cette
le fichier n'est généré que si vous utilisez le --pdf option.

api.tex
Le fichier LaTeX de niveau supérieur. Ce fichier importe les autres fichiers LaTeX, pour créer un
document unique et unifié.

api.dvi
Un fichier dvi contenant la documentation complète de l'API. Ce fichier est uniquement
généré si vous utilisez le --dvi option, la --PS option, ou la --pdf option.

api.ps Un fichier postscript contenant la documentation complète de l'API. Ce fichier est uniquement
généré si vous utilisez le --PS option ou le --pdf option.

module-module.tex
La documentation de l'API pour un module. module est le nom complet en pointillé du
modules, tels que sys or epydoc.epytext.

classe-classe.tex
La documentation de l'API pour une classe, une exception ou un type. classe est le complet
nom en pointillé de la classe, comme epydoc.epytext.Token ou array.ArrayType.
Ces fichiers de documentation de classe ne sont créés que si le --classes-separes
l'option est utilisée ; sinon, la documentation de chaque classe est incluse dans son
fichier de documentation du module.

DIAGNOSTIC

ÉPYTEXTE MARQUAGE ATTENTION MESSAGES
Les erreurs d'epytext sont causées par des docstrings epytext qui contiennent un balisage non valide. N'importe quand
une erreur epytext est détectée, la docstring en question est traitée comme un texte clair
docstring. Epydoc peut générer les erreurs d'epytext suivantes :

piscine lien cible.
La cible spécifiée pour une construction de lien en ligne (L{...}) n'est pas bien-
formé. Les cibles de lien doivent être des identifiants Python valides.

piscine Links cible.
La cible spécifiée pour une construction d'uri en ligne (Vous {...}) n'est pas bien formé.
Cela se produit généralement si le balisage en ligne est imbriqué dans la cible URI.

Des champs doit be at le top niveau.
La liste des champs (@pour moi, etc.) est contenu dans une autre structure de bloc
(comme une liste ou une section).

Des champs doit be le finale éléments.
La liste des champs (@pour moi, etc.) n'est pas à la fin d'une docstring.

Rubriques doit se produire at top niveau.
L'en-tête est contenu dans une autre structure de bloc (telle qu'une liste).

Non conforme docteur bloc échancrure.
Le bloc doctest s'enfonce au-delà de l'indentation de sa ligne d'invite initiale.

Non conforme titre échancrure.
Le titre d'une section n'est pas aligné à gauche avec les paragraphes de la
section qui le contient.

Non conforme paragraphe échancrure.
Les paragraphes d'un bloc ne sont pas alignés à gauche. Cette erreur est souvent
généré lorsque les docstrings en texte brut sont analysées à l'aide de epytext.

Invalide échapper.
Une séquence d'échappement inconnue a été utilisée avec la construction d'échappement en ligne
(E{...}).

Liste doit be dentelé.
Une ligne sans retrait immédiatement après un paragraphe commence par une puce de liste.
Epydoc ne sait pas si vous vouliez commencer un nouvel élément de liste ou si vous vouliez
paragraphe pour inclure un mot qui ressemble à une puce. Si vous aviez l'intention de
ancien, puis indenter la liste. Si vous vouliez ce dernier, changez le
le renvoi à la ligne du paragraphe, ou échapper le premier caractère du mot qui
ressemble à une balle.

Déséquilibré '{'.
La docstring contient des accolades non équilibrées. Epytext exige que toutes les accolades
doit être équilibré. Pour inclure une seule accolade déséquilibrée, utilisez l'échappement
séquences E{lb} (accolade gauche) et E{rb} (accolade droite).

Déséquilibré '}'.
La docstring contient des accolades non équilibrées. Epytext exige que toutes les accolades
doit être équilibré. Pour inclure une seule accolade déséquilibrée, utilisez l'échappement
séquences E{lb} (accolade gauche) et E{rb} (accolade droite).

Inconnu en ligne balisage Étiquette.
Une balise inconnue a été utilisée avec la construction de balisage en ligne ( x{...} ).

faux souligner caractère pour cap.
Le caractère de soulignement utilisé pour cet en-tête de section n'indique pas une
niveau de section approprié. Le caractère "=" doit être utilisé pour souligner
sections; "-" pour les sous-sections ; et "~" pour les sous-sections.

Possible mal formaté champ article.
Epytext a détecté une ligne qui ressemble à un élément de champ, mais n'est pas correctement
formaté. Cela se produit généralement lorsque les deux points de fin (":") ne sont pas inclus
dans la balise de champ.

Possible titre faute de frappe.
Epytext a détecté une paire de lignes qui ressemble à un titre, mais le nombre de
les caractères de soulignement ne correspondent pas au nombre de caractères de l'en-tête.
Le nombre de caractères dans ces deux lignes doit correspondre exactement pour qu'ils soient
considéré comme un titre.

CHAMP MISES EN GARDE
Les avertissements de champ sont causés par des docstrings contenant des champs invalides. Le contenu de
les champs invalides sont généralement ignorés. Epydoc peut générer le champ suivant
mises en garde:

@pour moi pour inconnu paramètre arrêter.
Un champ @param a été utilisé pour spécifier le type d'un paramètre qui n'est pas
inclus dans la signature de la fonction. Ceci est généralement causé par une faute de frappe dans
le nom du paramètre.

Étiquette fait pas attendre an argument.
La balise de champ Étiquette a été utilisé avec un argument, mais il n'en prend pas un.

Étiquette attendu an argument.
La balise de champ Étiquette a été utilisé sans argument, mais il en requiert un.

@type pour inconnu paramètre arrêter.
Un champ @type a été utilisé pour spécifier le type d'un paramètre qui n'est pas inclus
dans la signature de la fonction. Ceci est généralement causé par une faute de frappe dans le
le nom du paramètre.

@type pour inconnu variable var.
Un champ @type a été utilisé pour spécifier le type d'une variable, mais aucun autre
l'information est connue sur la variable. Ceci est généralement causé par une faute de frappe dans
le nom de la variable.

Inconnu champ Étiquette Étiquette.
Une docstring contient un champ avec la balise inconnue Étiquette.

Redéfinition of champ.
Plusieurs balises de champ définissent la valeur de champ dans la même docstring, mais champ
ne peut prendre qu'une seule valeur.

EXEMPLES

épidoc -n épidoc -u http://epydoc.sf.net épydoc/
Générez la documentation de l'API HTML pour le package epydoc et tous ses
sous-modules et écrivez la sortie dans le html annuaire. Dans les en-têtes et
pieds de page, utiliser épidoc comme nom du projet, et http://epydoc.sf.net comme le projet
URL.

épidoc --pdf -n épidoc épydoc/
Générez la documentation de l'API LaTeX pour le package epydoc et tous ses
sous-modules et écrivez la sortie dans le latex répertoire.

EXIT STATUT

0 Exécution réussie du programme.

1 Erreur d'utilisation.

2 Epydoc a généré une erreur ou un avertissement, et l'une des options --échec sur erreur,
--échec sur avertissement, or --fail-on-docstring-avertissement a été précisé.

d’autres Erreur interne (exception Python).

Utiliser epydoc en ligne à l'aide des services onworks.net