epydoc: en línea en la nube

PROGRAMA:

NOMBRE

epydoc: genera documentación de API a partir de cadenas de documentos de Python

SINOPSIS

epidoc [ DE ACTUAR!] [opciones] nombres ...

DESCRIPCIÓN

epidoc genera documentación de API para módulos y paquetes de Python, en función de su
docstrings. Un lenguaje de marcado ligero llamado epitexto se puede utilizar para formatear
docstrings y para agregar información sobre campos específicos, como parámetros e instancias
variables. Epydoc también comprende las cadenas de documentos escritas en ReStructuredText, Javadoc y
Texto sin formato. Actualmente, epydoc admite dos formatos de salida básicos: HTML y LaTeX.

La documentación de la API HTML producida por epidoc consta de un conjunto de archivos HTML, que incluyen:
una página de documentación API para cada clase y módulo; una página de código fuente resaltada por sintaxis
para cada módulo; una página de índice de identificadores; una página de ayuda; y una tabla basada en marcos de
contenido. Cuando sea apropiado, epidoc también generará páginas de índice para errores, definidas
términos y tareas pendientes; una página de jerarquía de clases; y una página de jerarquía de paquetes.

La documentación de la API de LaTeX producida por epidoc consta de un archivo LaTeX principal y un archivo LaTeX
archivo para cada módulo. Si utiliza --dvi, --PDo --pdf , después epidoc invocará externo
comandos para convertir la salida LaTeX al formato solicitado. Tenga en cuenta que los archivos LaTeX
que contiene la documentación de los módulos individuales se puede incluir como capítulos o
secciones de otros documentos LaTeX, usando LaTeX \incluir mando. Si quieres
incluir clases individuales en otros documentos LaTeX, luego use el - clases-separadas
opción para producir un archivo LaTeX separado para cada clase.

epidoc también se puede utilizar para comprobar la integridad de la documentación de la API. Por defecto,
Comprueba que todos los paquetes, módulos, clases, métodos y funciones públicos tengan una cadena de documentación.
descripción. La --pruebas La opción se puede utilizar para especificar pruebas adicionales a realizar.

REPRODUCIBLE CONSTRUYE COMPORTAMIENTO

El uso de la fecha actual dentro de la documentación generada por Epydoc da como resultado documentación que
es "irreproducible", lo que significa que el contenido de los archivos cambia de una compilación a otra
incluso si el árbol de origen no lo hace. Para facilitar la generación de compilaciones reproducibles, este
La versión de Epydoc admite dos funciones: --no-incluye-tiempo de compilación opción y el
FUENTE_FECHA_EPOCH Variable ambiental.

El --no-incluye-tiempo de compilación La opción se puede utilizar cuando sepa de antemano que no necesita
construya marcas de tiempo en su documentación generada. los FUENTE_FECHA_EPOCH entorno
La variable está diseñada para ser utilizada por sistemas de empaquetado, como el proceso de construcción de Debian.
Los sistemas de embalaje se establecerán FUENTE_FECHA_EPOCH a una marca de tiempo sensible que de alguna manera es
relacionado con el estado del árbol de origen, y esa marca de tiempo será utilizada por Eypdoc en lugar de
que la marca de tiempo actual. Construye usando FUENTE_FECHA_EPOCH será así reproducible.

OPCIONES

Las opciones de Epydoc se dividen en seis categorías: opciones básicas, acciones, generación
opciones, opciones de salida, opciones de gráficos y opciones de valor de retorno.

ED. BÁSICA OPCIONES

nombres...
La lista de objetos que deben documentarse. Los objetos se pueden especificar usando
Nombres con puntos de Python (como os.ruta), nombres de archivo (como epydoc / epytext.py),
o nombres de directorio (como epydoc /). Los nombres de directorio especifican paquetes y
se amplían para incluir todos los submódulos y subpaquetes. Si quieres
excluir ciertos submódulos o subpaquetes, utilice el --excluir opción
(descrito abajo).

--config presentar
Un archivo de configuración, especificando adicionales opcionesy/onombres. Esta opción
puede repetirse.

--q, --tranquilo, --v, --verboso
Produzca un resultado bastante (o detallado). Si se usa varias veces, esta opción
produce una salida sucesivamente más silenciosa (o detallada).

--depurar
Muestra trazas completas de errores internos.

- término simple
No intente utilizar el control del cursor o del color al mostrar la barra de progreso,
advertencias o errores.

ACCIONES

--html Escribe salida HTML. [defecto]

--látex Escribe salida LaTeX.

--dvi Escribe salida DVI.

--PD Escriba la salida PostScript.

--pdf Escriba la salida de Adobe Acrobat (pdf).

--cheque Realice controles de integridad de la documentación.

--pepinillo Escribe la documentación en un archivo pickle.

GENERACION OPCIONES

--docformato formato
Establecer el valor predeterminado para __docformato__ a formato. __docformato__ es un modulo
variable que especifica el lenguaje de marcado para las cadenas de documentos en un módulo.
Su valor consiste en el nombre de un lenguaje de marcado, opcionalmente seguido de un
código de idioma (como en para inglés). Para obtener una lista de los lenguajes de marcado
actualmente reconocido por epydoc, ejecute epidoc --ayuda formato de documento.

--sólo análisis
Reúna toda la información sobre los objetos documentados analizando los
Código fuente de Python; en particular, haz no usa la introspección para reunir
información sobre los objetos documentados. Esta opción debe usarse cuando
epydoc se ejecuta en código que no es de confianza; o en código que no se puede introspectar
debido a dependencias faltantes, o porque la importación causaría efectos no deseados
efectos secundarios.

--sólo introspectiva
Reúna toda la información sobre los objetos documentados mediante introspección; en
particular, hacer no recopilar información analizando la fuente de Python del objeto
código.

--excluir PATRÓN
No documente ningún objeto cuyo nombre coincida con la expresión regular dada
patrón.

--excluir-introspección PATRÓN
No utilice la introspección para recopilar información sobre ningún objeto cuyo nombre
coincide con la expresión regular dada.

--excluir-analizar PATRÓN
No utilice el análisis de código fuente de Python para recopilar información sobre ningún objeto
cuyo nombre coincide con la expresión regular dada.

--herencia formato
El formato que debe usarse para mostrar métodos heredados, variables y
propiedades en las tablas de "resumen" generadas. Si formato está "agrupado", entonces
Los objetos heredados se agrupan en grupos, según la clase a la que pertenecen.
heredado de. Si formato está "enumerado", los objetos heredados se enumeran en un
lista corta al final de la tabla resumen. Si formato está "incluido", entonces
los objetos heredados se mezclan con los objetos no heredados. El formato predeterminado
para la salida HTML está "agrupado".

- show-privado, --no-privado
Estas opciones controlan si se genera documentación para objetos privados.
De forma predeterminada, la documentación generada incluye objetos privados y los usuarios pueden
elija si desea ver los objetos privados o no, haciendo clic en "mostrar privado"
y "ocultar enlaces privados". Pero si desea disuadir a los usuarios de que
acceder a objetos privados, entonces es posible que prefiera no generar documentación
para objetos privados.

- espectáculo-importaciones, --no importaciones
Estas opciones controlan si las importaciones de módulos se incluyen en el archivo generado.
documentación. Por defecto, las importaciones no están incluidas.

--mostrar-código fuente, --sin código fuente
Estas opciones controlan si epydoc debe generar resaltado de sintaxis
páginas que contienen el código fuente de cada módulo en la salida HTML. Por defecto,
se generan las páginas del código fuente.

--incluir-registro
Genera una página HTML registro-epydoc.html que contiene todos los mensajes de error y advertencia
que son generados por epydoc, y lo incluyen en la salida generada.

--no-incluye-tiempo de compilación
No imprima el tiempo de construcción en el pie de página. Esto es útil si está
tratando de generar compilaciones reproducibles, donde cada compilación contra un determinado
La versión de un árbol de origen produce exactamente los mismos artefactos.

SALIDA OPCIONES

-o dir, --producción dir
El directorio de salida. Si dir no existe, entonces se creará. Si no
se especifica el directorio de salida, luego el nombre de la acción (por ejemplo, html or pdf). html

-c hoja, --css hoja
Hoja de estilo CSS para archivos de salida HTML. Si hoja es un archivo, luego la hoja de estilo
se copia de ese archivo; de lo contrario, hoja se toma como el nombre de un
hoja de estilo incorporada. Para obtener una lista de las hojas de estilo integradas, ejecute epidoc --ayuda
css. Si no se especifica una hoja de estilo CSS, la hoja de estilo predeterminada es
usado.

-n nombre , --nombre nombre
El nombre del proyecto cuya documentación se está generando.

-u url, --url url
La URL de la página de inicio del proyecto.

--enlace de navegación html
Código HTML para el enlace de la página de inicio en la barra de navegación HTML. Si este código HTML
contiene hipervínculos (<a href = ...>), luego se insertará literalmente. Si
no contiene ningún hipervínculo y se especifica una URL del proyecto (con
--url), luego se agrega al vínculo un hipervínculo a la URL especificada.

--archivo de ayuda presentar
Un archivo de ayuda alternativo. presentar debe contener el cuerpo de un archivo HTML -
Se le agregarán barras de navegación.

- marcos de espectáculos, --sin marcos
Estas opciones controlan si la salida HMTL incluirá una tabla basada en marcos de
página de contenido. De forma predeterminada, se incluye la tabla de contenido basada en marcos.

- clases-separadas
En la salida de LaTeX, describa cada clase en una sección separada del
documentación, en lugar de incluirlos en la documentación para su
módulos. Esto crea un archivo LaTeX separado para cada clase, por lo que también se puede
útil si desea incluir la documentación para una o dos clases como
secciones de su propio documento LaTeX.

GRAFICO OPCIONES

--grafico tipo de gráfico
Incluir gráficos de tipo tipo de gráfico en la salida generada. Se generan gráficos
utilizando el ejecutable Graphviz dot. Si este ejecutable no está en la ruta, entonces
use --ruta de puntos para especificar su ubicación. Esta opción puede repetirse para incluir
múltiples tipos de gráficos en la salida. tipo de gráfico debe ser uno de: all,
árbol de clases, gráfico de llamadaso árbol de clases uml.

--ruta de puntos camino
El camino hacia Graphviz punto ejecutable.

--graph-fuente fuente
El nombre de la fuente utilizada para generar gráficos Graphviz. (p. ej., helvética o
veces).

--tamaño de fuente del gráfico tamaño
El tamaño de la fuente utilizada para generar gráficos Graphviz, en puntos.

--pstat presentar
Un archivo de salida pstat, que se utilizará en la generación de gráficos de llamadas.

DEVOLUCION VALOR OPCIONES

--falla por error
Devuelve un estado de salida distinto de cero, que indica falla, si se detecta algún error.
encontrado.

- advertencia de falla
Devuelve un estado de salida distinto de cero, que indica falla, si hay errores o advertencias
se encuentran (sin incluir las advertencias de cadenas de documentos).

--fail-on-docstring-advertencia
Devuelve un estado de salida distinto de cero, que indica falla, si hay errores o advertencias
se encuentran (incluidas las advertencias de cadenas de documentos).

HTML ARCHIVOS

La documentación de la API HTML producida por epidoc consta de los siguientes archivos:

OBJETO DOCUMENTACIÓN PÁGINAS

index.html
El punto de entrada estándar para la documentación. Normalmente, index.html es una copia
del archivo de marcosmarcos.html). Pero si el --sin marcos se utiliza la opción, entonces
index.html es una copia de la página de inicio de la documentación de la API, que normalmente es la
página de documentación para el paquete o módulo de nivel superior (o la página de árboles si
no hay ningún paquete o módulo de nivel superior).

módulo-módulo.html
La documentación de API para un módulo. módulo es el nombre completo con puntos del
módulo, como sis or epiydoc.epytext.

clase-clase.html
La documentación de la API para una clase, excepción o tipo. clase es el completo
nombre de la clase con puntos, como epydoc.epytext.token or matriz.ArrayType.

módulo-pysrc.html
Una página resaltada por sintaxis que contiene el código fuente de Python para módulo. Esto
La página incluye enlaces a las páginas de documentación de la API.

módulo-árbol.html
La jerarquía del módulo.

árbol-de-clases.html
La jerarquía de clases. Esta página solo se genera si al menos una clase es
Documentada.

ÍNDICES

índice-identificador.html
Un índice de todos los identificadores documentados. Si el índice de identificador contiene más
más de 3,000 entradas, luego se dividirá en páginas separadas para cada letra,
llamado identificador-índice-a.html, índice-identificador-b.html, etc.

índice-término.html
Un índice de todos los términos de definición marcados explícitamente. Esta pagina es solo
generado si al menos un término de definición está marcado en una cadena de documentos formateada.

índice de errores.html
Un índice de todos los marcados explícitamente @insecto los campos. Esta página solo se genera si
al menos uno @insecto El campo aparece en una cadena de documentos formateada.

todo-index.html
Un índice de todos los marcados explícitamente @hacer los campos. Esta página solo se genera si
al menos uno @hacer El campo aparece en una cadena de documentos formateada.

cambiado-index.html
Un índice de todos los marcados explícitamente @cambió los campos. Esta página solo se genera
si al menos uno @cambió El campo aparece en una cadena de documentos formateada.

índice-obsoleto.html
Un índice de todos los marcados explícitamente @obsoleto los campos. Esta pagina es solo
generado si al menos uno @obsoleto El campo aparece en una cadena de documentos formateada.

desde-index.html
Un índice de todos los marcados explícitamente @ya que los campos. Esta página solo se genera
si al menos uno @ya que El campo aparece en una cadena de documentos formateada.

BASADO EN MARCOS MESA DE NOCHE OF CONTENIDO

marcos.html
El archivo de fotogramas principal. Dos marcos en el lado izquierdo de la ventana contienen un
tabla de contenido, y el marco principal en el lado derecho de la ventana contiene
Páginas de documentación de API.

toc.html
La página de la tabla de contenido de nivel superior. Esta página se muestra en la parte superior izquierda
marco de marcos.htmly proporciona enlaces a la toc-todo.html y
toc-módulo-módulo.html .

toc-todo.html
La tabla de contenido de todo el proyecto. Esta página se muestra en la
marco inferior izquierdo de marcos.htmly proporciona enlaces a todas las clases, tipos,
excepción, función y variable definida por el proyecto.

toc-módulo-módulo.html
La tabla de contenido de un módulo. Esta página se muestra en la parte inferior izquierda
marco de marcos.htmly proporciona enlaces a todas las clases, tipos, excepciones,
función y variable definida por el módulo. módulo es el completo punteado
nombre del módulo, como sis or epiydoc.epytext.

OTROS PÁGINAS

ayuda.html
La página de ayuda del proyecto. Esta página explica cómo utilizar y navegar por
página web producida por epydoc.

redirigir.html
Esta página utiliza javascript para traducir los nombres con puntos a sus correspondientes
URLs. Por ejemplo, en la documentación de epydoc, cargar la página
redirigirá automáticamente el
navegador para .

epiydoc.css
La hoja de estilo CSS utilizada para mostrar todas las páginas HTML.

epiydoc.js
Un archivo javascript usado para definir funciones javascript usadas por epydoc.

registro-epydoc.html
Una página que contiene un registro de todas las advertencias y errores generados por
epydoc, junto con una tabla que enumera todas las opciones que se utilizaron.

LÁTEX ARCHIVOS

La documentación de la API de LaTeX producida por epidoc consta de los siguientes archivos:

api.pdf
Un archivo de Adobe Acrobat (pdf) que contiene la documentación completa de la API. Esta
El archivo solo se genera si usa el --pdf .

api.tex
El archivo LaTeX de nivel superior. Este archivo importa los otros archivos LaTeX, para crear un
único documento unificado.

api.dvi
Un archivo dvi que contiene la documentación completa de la API. Este archivo es solo
generado si utiliza el --dvi opción, la --PD opción, o el --pdf .

api.ps Un archivo postscript que contiene la documentación completa de la API. Este archivo es solo
generado si utiliza el --PD opción o el --pdf .

módulo-módulo.tex
La documentación de API para un módulo. módulo es el nombre completo con puntos del
módulo, como sis or epiydoc.epytext.

clase-clase.tex
La documentación de la API para una clase, excepción o tipo. clase es el completo
nombre de la clase con puntos, como epydoc.epytext.token o array.ArrayType.
Estos archivos de documentación de clase solo se crean si el - clases-separadas
se utiliza la opción; de lo contrario, la documentación de cada clase se incluye en su
archivo de documentación del módulo.

La diagnostica

TEXTO EPITO MARGEN ADVERTENCIA MENSAJES
Los errores de Epytext son causados ​​por cadenas de documentos de epytext que contienen marcas no válidas. Cuando sea
se detecta un error de epytext, la cadena de documentos en cuestión se trata como texto sin formato
docstring. Epydoc puede generar los siguientes errores de epytext:

Malo enlace objetivo.
El destino especificado para una construcción de enlaces en línea (L {...}) no está bien-
formado. Los destinos de los enlaces deben ser identificadores de Python válidos.

Malo uri objetivo.
El destino especificado para una construcción de uri en línea (U {...}) no está bien formado.
Esto suele ocurrir si el marcado en línea está anidado dentro del destino URI.

Terrenos deben be at los parte superior .
La lista de campos (@param, etc.) está contenido en alguna otra estructura de bloque
(como una lista o una sección).

Terrenos deben be los final elementos.
La lista de campos (@param, etc.) no está al final de una cadena de documentos.

Encabezado deben ocurrir at parte superior .
El encabezado está contenido en alguna otra estructura de bloque (como una lista).

Incorrecto prueba bloquear sangría.
El bloque doctest se deforma más allá de la sangría de su línea de solicitud inicial.

Incorrecto Bóveda sangría.
El encabezado de una sección no está alineado a la izquierda con los párrafos de la
sección que lo contiene.

Incorrecto párrafo sangría.
Los párrafos dentro de un bloque no están alineados a la izquierda. Este error es a menudo
generado cuando se analizan cadenas de documentos de texto sin formato utilizando epytext.

Inválido escapar.
Se utilizó una secuencia de escape desconocida con la construcción de escape en línea
(MI{...}).

Listas deben be sangrado.
Una línea sin sangría inmediatamente después de un párrafo comienza con una viñeta de lista.
Epydoc no está seguro de si pretendía iniciar un nuevo elemento de la lista o si pretendía
párrafo para incluir una palabra que parezca una viñeta. Si pretendías el
primero, luego sangra la lista. Si pretendía lo último, cambie el
ajuste de palabras del párrafo, o escapar del primer carácter de la palabra que
parece una bala.

Desequilibrado '{'.
La cadena de documentos contiene llaves no balanceadas. Epytext requiere que todas las llaves
debe estar equilibrado. Para incluir una sola abrazadera desequilibrada, use el escape
secuencias E {lb} (llave izquierda) y E {rb} (llave derecha).

Desequilibrado '}'.
La cadena de documentos contiene llaves no balanceadas. Epytext requiere que todas las llaves
debe estar equilibrado. Para incluir una sola abrazadera desequilibrada, use el escape
secuencias E {lb} (llave izquierda) y E {rb} (llave derecha).

Desconocido en línea margen etiqueta.
Se usó una etiqueta desconocida con la construcción de marcado en línea ( x{...} ).

Mal subrayar personaje for encabezamiento.
El carácter subrayado utilizado para este encabezado de sección no indica un
nivel de sección apropiado. El carácter "=" debe usarse para subrayar
secciones; "-" para subsecciones; y "~" para subsecciones.

Posibles mal formateado campo ít.
Epytext detectó una línea que parece un elemento de campo, pero no está correctamente
formateado. Esto suele ocurrir cuando no se incluyen los dos puntos finales (":")
en la etiqueta de campo.

Posibles Bóveda error de tipografía.
Epytext detectó un par de líneas que parecen un encabezado, pero el número de
los caracteres subrayados no coinciden con el número de caracteres del encabezado.
El número de caracteres en estas dos líneas debe coincidir exactamente para que sean
considerado un título.

CAMPO ADVERTENCIAS
Las advertencias de campo son causadas por cadenas de documentos que contienen campos no válidos. Los contenidos de
los campos no válidos generalmente se ignoran. Epydoc puede generar el siguiente campo
advertencias:

@param for desconocido parámetro detener.
Se usó un campo @param para especificar el tipo de un parámetro que no es
incluido en la firma de la función. Esto suele deberse a un error tipográfico en
el nombre del parámetro.

etiqueta did no esperar an argumento.
La etiqueta de campo etiqueta se utilizó con un argumento, pero no se necesita.

etiqueta esperado an argumento.
La etiqueta de campo etiqueta se usó sin un argumento, pero requiere uno.

@tipo for desconocido parámetro detener.
Se usó un campo @type para especificar el tipo de un parámetro que no está incluido
en la firma de la función. Esto suele deberse a un error tipográfico en el
nombre del parámetro.

@tipo for desconocido variable var.
Se usó un campo @type para especificar el tipo de una variable, pero no otro
se conoce información sobre la variable. Esto suele deberse a un error tipográfico en
el nombre de la variable.

Desconocido campo etiqueta etiqueta.
Una cadena de documentos contiene un campo con la etiqueta desconocida etiqueta.

Redefinición of campo.
Varias etiquetas de campo definen el valor de campo en la misma cadena de documentos, pero campo
solo puede tomar un valor.

EJEMPLOS

epidoc -n epidoc -u http://epydoc.sf.net epydoc /
Genere la documentación de la API HTML para el paquete epydoc y todos sus
submódulos y escribe la salida en el html directorio. En los encabezados y
pies de página, uso epidoc como nombre del proyecto, y http://epydoc.sf.net como el proyecto
URL.

epidoc --pdf -n epidoc epydoc /
Genere la documentación de la API de LaTeX para el paquete epydoc y todos sus
submódulos y escribe la salida en el látex directorio.

SALIR ESTADO

0 Ejecución exitosa del programa.

1 Error de uso.

2 Epydoc generó un error o advertencia, y una de las opciones --falla por error,
- advertencia de falla, or --fail-on-docstring-advertencia fue especificado.

other Error interno (excepción de Python).

Utilice epydoc en línea utilizando los servicios de onworks.net