Documentación General (ReadTheDocs)¶
Introducción¶
La documentación general (Esta página en ReadTheDocs) contiene toda la información no específica de todos los proyectos del Joko Framework, no debe contener especificaciones de código de algún proyecto, eso se deja a cargo de los Javadocs hosteados en las Github Pages de cada proyecto, lo que sí va en esta página es todo lo demás como la Introducción de los proyectos, Guías de Uso/Guías de Instalación, Ejemplos/Tutoriales, etc.
Esta página se genera con la herramienta Sphinx utilizando páginas escritas en el lenguaje Markup “reStructuredText”, los archivos para generar la página se almacenan en un proyecto de Github (https://github.com/jokoframework/jokoframework.github.io) y la página se actualiza automáticamente cuando hay cambios en el proyecto mediante Webhooks.
Instrucciones para agregar documentación¶
A continuación un paso a paso de como agregar nuevas páginas al proyecto:
1- Clonar el proyecto que contiene la página de ReadTheDocs
2- El directorio /docs del proyecto es el que contiene todo lo relacionado a Sphinx y las páginas generadas, es lo que ReadTheDocs utilizará, si se quiere hacer una nueva página o modificar una vieja se debe utilizar el lenguaje reStructuredText, la generación de las páginas usando estos archivos es lo que Sphinx provee.
3- Los archivos escritos en reStructuredText del proyecto deben terminar en la extensión “.rst”, si se desea modificar la página de entrada esta se especifica en el archivo /docs/index.rst mientras que el resto de las páginas están en el directorio /docs/joko-docs/*** tratando de mantener una estructura donde un archivo es una división (No necesariamente una página). Si quiere incluir imágenes debe poner las imagenes a referenciar en un subdirectorio de /docs/_static/*** (Es recomendado seguir una misma notación en el directorio _static/*** que en el de joko-docs/***).
4- Instalar Sphinx solo si desea probar localmente como se va viendo la página, ReadTheDocs genera con Sphinx de su lado usando solo los archivos fuente escritos en reStructuredText.
La guía de instalación de Sphinx: ofrece múltiples opciones según el sistema operativo y la plataforma utilizada. La recomendación es hacerlo a través de los paquetes de Python “Pypi”, debido a que la versión disponible en el repositorio de Linux puede no ser la última.
4.1- Si quiere jugar con las configuraciones de Sphinx (No es necesario) se encuentran en /docs/conf.py (Archivo en Python, recuerde de indentar correctamente!)
4.2- Ademas de Sphinx debe descargar el “Theme” de ReadTheDocs actualmente utilizado (No viene por defecto), esto se isntala atravez del manejador de paquetes de Python “pip”
4.3- Cada Theme de Sphinx viene con propiedades que se pueden especificar en el archivo “conf.py” (Por ejemplo que tenga un botón o no al final de la página que lleva a la siguiente), si se cambia de Theme es casi seguro que habran problemas a la hora de generar la página porque las propiedades del Theme de Read The Docs utilizadas no existirán o estarán nombradas de forma distinta (Mirar asignación a variable “html_theme_options” en conf.py).
4.4- Para probar lo que va escribiendo puede construir el proyecto con sphinx localmente, en particular puede utilizar un regenerador “sphinx-autobuild” que viene incluido con Sphinx (Vera su pagina y se actualizará cuando encuentra cambios en el directorio/s especificado/s), el autobuild sirve su pagina en el localhost puerto 8000 por defecto (En su navegador ponga “localhost:8000” como URL y podrá acceder a esta página servida). El comando para levantar el regenerador (Corrido desde la carpeta raíz del proyecto) es: “sphinx-autobuild docs docs/_build/html”.
5- Una vez feliz con su página simplemente debe actualizar el repositorio (Si genero localmente con Sphinx no suba la carpeta “_build” donde se creo la página web, este proyecto solo contiene los archivos para generar no lo generado) con los nuevos cambios y mediante Webhooks se actualizará la página de ReadTheDocs en unos minutos (Verificar que lo hecho se vea como se quiere en ReadTheDocs, debido a que se reconstruye la página en su lado pueden haber opciones que no permanecen o que arman problemas, aunque esto solo ocurre cuando se entra a tocar cosas muy particulares).