Publicando documentación en RTD

Read the Docs simplifica la documentación de software, mediante la automatización del building, versionamiento y hosting de nuestros docs.

  1. Primero debemos subir la documentación generada con Sphinx a nuestro repositorio en Github. Ejecutar los comandos desde la carpeta raíz del repositorio:
git add .
git commit -m "Primer commit para creacion de Documentacion"
git push
  1. Entrar a nuestro dashboard de la página de RTD , y teniendo nuestra cuenta de Github asociada, importaremos el proyecto haciendo clic en Importar un proyecto:
_images/2_importar-proyecto-rtd.png

Dashboard de RTD - Botón Importar un proyecto

En la siguiente pantalla, actualizar la lista de repositorios con el botón de un símbolo de Actualizar. Seleccionar el repositorio de Github que vamos a importar haciendo clic en el botón +:

_images/3_importar-repo.png

Dashboard de RTD - Importar un repositorio

Luego revisar la opciones del proyecto como el nombre que tendrá la URL y clic en Siguiente:

_images/4_import-options.png

Dashboard de RTD - Opciones para importar

  1. Para hacer un build del repositorio desde RTD, clic en Build version:
_images/5_build-version.png

Dashboard de RTD - Build de repositorio

_images/6_compilacion-completada.png

Dashboard de RTD - Compilación completada

_images/7_compilacion-log.png

Dashboard de RTD - Log de compilación

  1. Ahora nuestra documentación se encuentra pública, estando hosteada por RTD bajo el dominio readthedocs.io. Podremos verla haciendo clic en el botón Ver documentación de la anterior pantalla:

Página web de ejemplo: https://mydocproject1.readthedocs.io/en/latest/

_images/8_web-resultado.png

Página de documentación hosteada bajo el dominio readthedocs.io

  1. Para cambiar el tema de la página web actual (Alabaster) al que usa RTD por defecto editar el archivo docs/source/conf.py comentando la línea de html_theme = 'alabaster':
1
2
3
4
5
6
 # -- Options for HTML output -------------------------------------------------

 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 #html_theme = 'alabaster'

Warning

El cambio de tema solo se está aplicando para la página pública, el tema no se aplica a los archivos locales.

Luego actualizar el repositorio de Github:

git add .
git commit -m "Deshabilitando tema por defecto de Sphinx"
git push

La página pública de la documentación ahora tendrá el tema de Read the Docs:

_images/10_rtd-theme.png

Tema de Read the Docs en página pública