Download documentosE Documentation
Document related concepts
no text concepts found
Transcript
documentosE Documentation Release 1.0 mfg November 25, 2015 Contents 1 Contenido de la carpeta DOCS 1.1 Estructura . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 2 Instalación de Sphinx 2.1 Instalacion de librerias Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Creacion de proyecto sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Generación de HTML a partir de los Documentos rst. . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 5 6 3 I Archivo 3.1 AAAAAXXXXX-8888 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Generación de HTML a partir de los Documentos rst. . . . . . . . . . . . . . . . . . . . . . . . . . 7 7 7 8 4 Indices and tables 9 i ii documentosE Documentation, Release 1.0 Contents: Contents 1 documentosE Documentation, Release 1.0 2 Contents CHAPTER 1 Contenido de la carpeta DOCS A continuacion se muestra la estructura de directorios y archivos dentro la carpeta docs 1.1 Estructura contenido.rts documentacion-tecnica/ guia-de-inicio.rts guia-de-instalacion.rts manuales/ aplicación/ ———-app/ —————-controller/ —————-view/ —————-model/ ——— public/ —————-css/ —————font/ —————img/ —————js/ —————jquery/ referencias-tecnicas/ glosario-de-terminos.rts anexos/ 3 documentosE Documentation, Release 1.0 4 Chapter 1. Contenido de la carpeta DOCS CHAPTER 2 Instalación de Sphinx Sphinx es una distribución de Python, para instalarlo es necesario tener Python, este ya viene instalado en las distribuciones de Linux. 2.1 Instalacion de librerias Python Para instalar el repositorio de librerias de python se debe realizar: $ sudo apt-get install python-pip python-dev build-essential Luego para instalar Sphinx se realiza mediante el siguiente comando $ easy_install sphinx 2.2 Creacion de proyecto sphinx Para crear un proyecto Sphinx se debe ingresar a la carpeta donde estaran los documentos en formato .rst (restucturedText) y se genera el proyecto mediante la siguiente orden: $ sphinx-quickstart Seguir los pasos • Root path : el directorio base donde estaran la documentacion (por ejemplo /dir/docs/). Si se esta ubicado en el directorio colocar ”.” • Project name: Nombre del proyecto. (Ejemplo: Documentos Estructurados) • Author: Nombre del autor que tendra la documentacion. (Ejemplo: NN). No se puede dejar en blanco. • Version: Version del proyecto (ejemplo: 1.0) • Release: Version del proyecto liberado (ejemplo: 1.0) • Seguir las otras opciones de configuracion por defecto (presionando enter, con la configuracion propuesta por defecto), con excepcion de la opcion: autodoc: la cual se debe colocar “Y” Seguir el resto de la configuracion por defecto (simplemente presionando enter) 5 documentosE Documentation, Release 1.0 2.3 Generación de HTML a partir de los Documentos rst. Una vez creada la estructura del proyecto (configurado con sphinx-quickstart), en la carpeta docs se tienen los siguientes elementos nuevos: • Makefile: Archivo que contiene instrucciones para compilar salidas de documentación cuando se usa el comando make . • _build: Este es el directorio donde los archivos generados (html, pdf, LaTex, etc) serán colocados Después de que una salida específica es desencadenada. • _static: Los archivos que no son parte del código de origen (como las imágenes) son colocados aquí y después se enlazan en el directorio de compilación. • conf.py: Este es un archivo de Python que contiene valores de configuración para Sphynx, incluyendo aquellos seleccionados cuando sphinx-quickstart fue ejecutado en el terminal. • index.rst: La raíz del proyecto de documentación. En la carpeta docs, se alojaran los archivos rst, y de ser necesario estarán organizados en subdirectorios. Abrir el archivo index.rst, y modificarlo según las necesidades. Lo que si es importante es hacer referencia a los documentos rst existentes, para ello se deben aumentar los nombres de los archivos en el archivo index.rst debajo de la directiva :maxdepth, como se muestra a continuación. Estos archivos deben ser referenciados manteniendo tres espacios en blanco desde el borde izquierdo, se puede omitir la extensión rst. Luego para generar los archivos html se debe ejecutar la orden en la carpeta raiz (docs) donde se ecnuentran los documentos rst: Esto genera los html dentro de _buil/html donde se encuentra el archivo index.html el cual la raiz de la generacion html. docs/_build/html/index.html 6 Chapter 2. Instalación de Sphinx CHAPTER 3 I Archivo Sphinx es una distribución de Python, para instalarlo es necesario tener Python, este ya viene instalado en las distribuciones de Linux. 3.1 AAAAAXXXXX-8888 Para instalar el repositorio de librerias de python se debe realizar: $ sudo apt-get install python-pip python-dev build-essential Luego para instalar Sphinx se realiza mediante el siguiente comando $ easy_install sphinx 3.2 Conclusion Para crear un proyecto Sphinx se debe ingresar a la carpeta donde estaran los documentos en formato .rst (restucturedText) y se genera el proyecto mediante la siguiente orden: $ sphinx-quickstart Seguir los pasos • Root path : el directorio base donde estaran la documentacion (por ejemplo /dir/docs/). Si se esta ubicado en el directorio colocar ”.” • Project name: Nombre del proyecto. (Ejemplo: Documentos Estructurados) • Author: Nombre del autor que tendra la documentacion. (Ejemplo: NN). No se puede dejar en blanco. • Version: Version del proyecto (ejemplo: 1.0) • Release: Version del proyecto liberado (ejemplo: 1.0) • Seguir las otras opciones de configuracion por defecto (presionando enter, con la configuracion propuesta por defecto), con excepcion de la opcion: autodoc: la cual se debe colocar “Y” Seguir el resto de la configuracion por defecto (simplemente presionando enter) 7 documentosE Documentation, Release 1.0 3.3 Generación de HTML a partir de los Documentos rst. Una vez creada la estructura del proyecto (configurado con sphinx-quickstart), en la carpeta docs se tienen los siguientes elementos nuevos: • Makefile: Archivo que contiene instrucciones para compilar salidas de documentación cuando se usa el comando make . • _build: Este es el directorio donde los archivos generados (html, pdf, LaTex, etc) serán colocados Después de que una salida específica es desencadenada. • _static: Los archivos que no son parte del código de origen (como las imágenes) son colocados aquí y después se enlazan en el directorio de compilación. • conf.py: Este es un archivo de Python que contiene valores de configuración para Sphynx, incluyendo aquellos seleccionados cuando sphinx-quickstart fue ejecutado en el terminal. • index.rst: La raíz del proyecto de documentación. En la carpeta docs, se alojaran los archivos rst, y de ser necesario estarán organizados en subdirectorios. Abrir el archivo index.rst, y modificarlo según las necesidades. Lo que si es importante es hacer referencia a los documentos rst existentes, para ello se deben aumentar los nombres de los archivos en el archivo index.rst debajo de la directiva :maxdepth, como se muestra a continuación. Estos archivos deben ser referenciados manteniendo tres espacios en blanco desde el borde izquierdo, se puede omitir la extensión rst. Luego para generar los archivos html se debe ejecutar la orden en la carpeta raiz (docs) donde se ecnuentran los documentos rst: Esto genera los html dentro de _buil/html donde se encuentra el archivo index.html el cual la raiz de la generacion html. docs/_build/html/index.html 8 Chapter 3. I Archivo CHAPTER 4 Indices and tables • genindex • modindex • search 9