114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# Documentación i18n con MkDocs
|
|
|
|
Este repositorio contiene la documentación multilingüe (español e inglés) gestionada con MkDocs.
|
|
|
|
## 1. Estructura del Proyecto
|
|
|
|
La carpeta principal `i18n` está organizada de la siguiente manera:
|
|
|
|
```
|
|
i18n-docu/
|
|
├── docs/
|
|
│ ├── assets/
|
|
│ │ ├── css/
|
|
│ │ └── images/
|
|
│ ├── en/
|
|
│ │ ├── administration/
|
|
│ │ ├── developer/
|
|
│ │ ├── index_installation.md
|
|
│ │ ├── index_release.md
|
|
│ │ └── index.md
|
|
│ └── es/
|
|
│ ├── administration/
|
|
│ ├── developer/
|
|
│ ├── index_installation.md
|
|
│ ├── index_release.md
|
|
│ └── index.md
|
|
├── requirements.txt
|
|
├── setup_venv.sh
|
|
└── README.md
|
|
```
|
|
|
|
* `docs/`: Contiene todos los archivos de documentación
|
|
* `assets/`: Recursos estáticos como CSS e imágenes
|
|
* `en/`: Documentación en inglés
|
|
* `es/`: Documentación en español
|
|
|
|
## 2. Configuración del Entorno
|
|
|
|
Para configurar el entorno de desarrollo, utiliza el script proporcionado que creará un entorno virtual e instalará todas las dependencias necesarias:
|
|
|
|
```bash
|
|
# Desde la carpeta raíz del proyecto i18n-docu
|
|
./setup_venv.sh
|
|
```
|
|
|
|
El script realiza las siguientes acciones:
|
|
1. Crea un entorno virtual Python llamado `og_venv`
|
|
2. Activa el entorno virtual
|
|
3. Instala todas las dependencias desde `requirements.txt`
|
|
|
|
Para activar manualmente el entorno virtual después de la configuración inicial:
|
|
|
|
```bash
|
|
source og_venv/bin/activate
|
|
```
|
|
|
|
## 3. Iniciando el Servidor MkDocs
|
|
|
|
Una vez que el entorno virtual esté activado, puedes iniciar el servidor MkDocs con la siguiente sintaxis:
|
|
|
|
```bash
|
|
mkdocs serve -a IP:PUERTO
|
|
```
|
|
|
|
Por ejemplo, para iniciar el servidor en la dirección 127.0.0.1 y el puerto 8000:
|
|
|
|
```bash
|
|
mkdocs serve -a 127.0.0.1:8000
|
|
```
|
|
|
|
También puedes ejecutar el servidor con la configuración predeterminada:
|
|
|
|
```bash
|
|
mkdocs serve
|
|
```
|
|
|
|
Esto iniciará el servidor en http://127.0.0.1:8000 por defecto.
|
|
|
|
## 4. Generación del Build
|
|
|
|
Para generar la versión estática de la documentación (build), ejecuta:
|
|
|
|
```bash
|
|
mkdocs build
|
|
```
|
|
|
|
Este comando creará una carpeta `site/` con todos los archivos HTML y recursos necesarios para publicar la documentación. Los archivos generados se pueden desplegar en cualquier servidor web estático.
|
|
|
|
## 5. Generación de PDFs
|
|
|
|
Para generar versiones en PDF de la documentación, utiliza la variable de entorno `ENABLE_EXPORT_PDF`:
|
|
|
|
```bash
|
|
ENABLE_EXPORT_PDF=1 mkdocs build
|
|
```
|
|
|
|
Esto generará archivos PDF correspondientes a cada página de la documentación y los incluirá en la carpeta `site/pdf/`.
|
|
|
|
## 6. Gestión Multilingüe
|
|
|
|
La documentación se mantiene en dos idiomas: español (primario) e inglés (secundario).
|
|
|
|
Proceso de trabajo para la documentación multilingüe:
|
|
|
|
1. Primero se crean/editan los archivos en español dentro de la carpeta `docs/es/`
|
|
2. Luego estos archivos se traducen y se colocan en la carpeta `docs/en/` manteniendo la misma estructura de carpetas y nombres de archivo
|
|
|
|
Por ejemplo:
|
|
- Si se edita `docs/es/developer/api.md`
|
|
- La versión en inglés debe crearse en `docs/en/developer/api.md`
|
|
|
|
>[!TIP]
|
|
> Mantener sincronizadas ambas versiones cada vez que se realicen cambios en los documentos. No obstante, se recomienda realizar la traducción una vez se tenga una versión definitiva del documento en español.
|