Estructura de documentación#
Tras la instalación y configuración del entorno, es importante conocer la estructura que utiliza Linkaform para mantener su contenido.
Carpetas#
En su repositorio podrá encontrar las siguientes carpetas donde:
.
├── build
├── conf.py
├── content
├── docker-compose.yml
├── Dockerfile
├── extensions
├── LICENSE
├── local_build
├── locale
├── Makefile
├── README.md
├── requirements.txt
└── static
Nombre |
Descripción |
|---|---|
Build |
Carpeta que se genera al hacer build de su proyecto. |
Content |
Carpeta dónde se almacena la documentación escrita en rst. |
Extensions |
Carpeta que se genera al instalar una extensión nueva. |
Locale |
Carpeta que contiene archivos .po útiles para traducciones de las páginas. |
Static |
Carpeta que almacena archivos sobre las personalizaciones. |
Conf.py |
Archivo que contiene la configuración principal de Sphinx. (Consulte Archivo conf.py para más detalles) |
Carpeta build#
Esta carpeta contiene los archivos generados por Sphinx, como la documentación en formato HTML, PDF, etc. Los archivos en esta carpeta son los que se pueden distribuir o publicar para que otros los consulten.
.
├── Usuario
├── Desarrollador
├── Contribución
├── genindex.html
├── _images
├── index.html
├── objects.inv
├── search.html
├── searchindex.js
├── _sources
├── _sphinx_design_static
├── _static
└── _video_thumbnail
Nombre |
Descripción |
|---|---|
_images |
En esta carpeta, se almacena todas las imágenes que se utilizan en la documentación (gráficos o imágenes). |
_static |
Almacena archivos estáticos utilizados por los temas en la documentación (archivos CSS, imágenes o archivos JavaScript). |
.doctrees |
Contiene archivos temporales utilizados para agilizar la generación de la documentación. |
objects.inv |
Se utiliza para generar un índice de objetos en la documentación. Ayuda a vincular y buscar elementos específicos. |
index.rst |
Archivo principal que debe ejecutar en su navegador (Generar documentación ). |
arch.html |
Los archivos que llevan la terminación .html son archivos rst convertidos a html para presentarse en formato web. |
Carpeta content#
La carpeta content alberga archivos fuente de la documentación en formato ReStructuredText. Sphinx utiliza estos archivos como base para generar la documentación final. Es aqui donde se escribe la documentación!!!
├── Contribución
│ ├── Errores.rst
│ ├── Estructura_sphinx.rst
│ ├── index.rst
│ ├── Instalación.rst
│ ├── Introducción_sphinx.rst
│ ├── Personalización.rst
│ └── reStructuredText.rst
├── Desarrollador
│ ├── index.rst
│ ├── Módulos
│ └── Reportes
├── imgs
│ ├── Contribución
│ ├── flecha_roja.png
│ ├── Linkaform
│ ├── Modulos
│ └── Reportes
├── index.rst
└── locale
└── en
Al comenzar con su proyecto cree una carpeta con un nombre descriptivo.
Prudencia
Independientemente del contenido que desee crear, identifique al público al que va dirigido. Si está elaborando documentación para desarrolladores, cree una carpeta dentro de la sección de Desarrollador. En caso de estar dirigido a los usuarios, cree una carpeta en usuario.
Si planea utilizar imágenes, cree una nueva carpeta con el nombre de su proyecto dentro de la carpeta imgs. Dentro de esta carpeta, puede organizar las imágenes de la manera que le resulte más cómoda.
Importante
Si se encuentra trabajando en una sección nueva asegúrese de incluir su indice en el toctree del index principal.
Carpeta static#
Carpeta que almacena archivos sobre personalización como hojas de estilo (CSS), imágenes o archivos JavaScript.
├── css
│ └── custom.css
├── directorio4.html
└── img
├── Linkaform_dark.png
└── Linkaform_light.png
Importante
Esta carpeta solo se utiliza para modificaciones que afectan a toda la documentación.
En caso de aplicar estilos CSS, puede hacerlo en el archivo custom.css, solamente asegúrese de agregar comentarios que identifiquen su propósito.
Dentro de la carpeta img, se almacenan imágenes que se desean mostrar en todas las páginas, como los logotipos de Linkaform.
Carpetas extra#
Otras carpetas importantes que son generadas al momento de instalar alguna extensión, son las siguientes:
_sphinx_design_static: Esta carpeta contiene archivos estáticos derivados de la extensión Sphinx design para diseñar componentes web responsivos.
Cards: Carpeta dentro de extensions, derivada de la extensión Cards para el uso de tarjetas personalizadas.
_video_thumbnail: Carpeta generada por la extensión sphinxcontrib.youtube, útil para incluir videos. En esta carpeta se almacenan miniaturas o recursos relacionados con los videos.
En esta sección, se han explicado las carpetas principales que se utilizarán para crear la documentación. En secciones posteriores, se presentarán ejemplos de cómo escribir documentación con reStructuredText y cómo añadirlos al índice principal.