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:

Directory Tree

.
├── build
├── conf.py
├── content
├── docker-compose.yml
├── Dockerfile
├── extensions
├── LICENSE
├── local_build
├── locale
├── Makefile
├── README.md
├── requirements.txt
└── static

Carpetas de interés

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.

Directory Tree

.
├── Usuario
├── Desarrollador
├── Contribución
├── genindex.html
├── _images
├── index.html
├── objects.inv
├── search.html
├── searchindex.js
├── _sources
├── _sphinx_design_static
├── _static
└── _video_thumbnail

Carpetas de interés

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!!!

Directory Tree
.
├── 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
│   ├── PDF
│   └── Reportes
├── imgs
│   ├── Contribución
│   ├── flecha_roja.png
│   ├── Linkaform
│   ├── Modulos
│   ├── PDF
│   └── 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.

Directory Tree
.
├── 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.