Agregar documentación general a Joko Framework

=Agregar documentación general a Joko Framework=

Introducción
Primero que nada definimos la documentación general del Framework como toda documentación que no sea la especificación del código de los proyectos (Eso se deja para los Javadocs) como son la Introducción de los proyectos, Guía de Uso/Instalación, Ejemplos/Tutoriales, etc.

La página web esta hosteada en ReadTheDocs (Página que provee hosting gratuito para proyectos Open Source) en donde de su lado se utiliza la herramienta Sphinx para generar una página web de archivos escritos en el lenguaje Markup "reStructuredText".

Paso a paso 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 los archivos para generar la página de ReadTheDocs https://github.com/jokoframework/jokoframework.github.io 2- El directorio /docs del proyecto es el que contiene todo lo relacionado a Sphinx (conf.py) y las páginas generadas(Archivos .rst y imagenes utilizadas), esto es lo que ReadTheDocs utilizará para generar la página con Sphinx, si se quiere hacer una nueva página o modificar una vieja se debe utilizar el lenguaje reStructuredText reStructuredText Cheatsheet: https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst

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 imágenes 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 Instalación de Sphinx: http://www.sphinx-doc.org/en/master/usage/installation.html

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!) Opciones de configuración: http://www.sphinx-doc.org/en/master/config.html

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" Instalación de Sphinx RTD Theme: https://github.com/rtfd/sphinx_rtd_theme

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). Propiedades aceptadas por el Sphinx RTD Theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html

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”. Sphinx Autobuild: https://pypi.python.org/pypi/sphinx-autobuild

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) Página de Joko Framework en ReadTheDocs: http://jokoframeworkgithubio.readthedocs.io/en/latest/#