Documentar nuestra aplicación tiene una importancia capital. No podemos esperar que mucha gente use nuestra aplicación si no saben cómo.
Hay muchas maneras de documentar nuestra aplicación. Podríamos escribir un fichero de texto e incluirlo entre nuestros ficheros fuente, pero ese sería precisamente su problema: al hacerlo, nuestra documentación se mezclaría con otros muchos ficheros y carpetas y podría pasar desapercibido fácilmente. Además debería ser un fichero púramente textual si no queremos obligar a nuestros usuarios a contar con un lector específico, por ejemplo word, acrobat, etc.
Otra manera, y la que vamos a cubrir aquí, es usar un lenguaje de marcado para escribir un fichero de texto que pueda luego ser utilizado como fuente por un compilador para crear documentación web con un formato visualmente atractivo. Hay muchos lenguajes de marcado, pero los dos principales que vamos a cubrir aquí son Markdown y reStructuredText (RST): el último es más extensible y el estándar de facto en el mundo Python, aunque el primero es más sencillo, fácil de usar y la opción por defecto de Github.
Para alojar la documentación web generada se puede usar cualquier servidor web pero hay muchos servicios gratuitos para proyectos de código abierto. Aquí vamos a revisar las wikis de Github y el servicio de ReadTheDocs.
La opción más sencilla es Github, que permite alojar documentación a través de sus páginas de wiki.
Dichas páginas permiten utilizar tanto Markdown como RST, así como editar las páginas tanto directamente con un navegador como descargándolas como un repositorio git, aparte del de nuestro código fuente. Sólo hay que tener en cuenta que aunque se pueden hacer ramas (branches) en el repositorio de nuestra documentación, sólo serán visibles los pushes a la rama master.
La URL para clonar el reposiorio de la wiki se puede ver en la pestaña de Github referente a la wiki. Además hay que tener en cuenta que a la hora de hacer pushes los fichero añadidos deberán tener una extensión coherente con el lenguaje de marcado utilizado: .md para Markdown o .rst para reStructuredText.
Además. la edición de la documentación puede realizarse colaborativamente asignando permisos a diferentes usuarios.
Para crear una nueva wiki en nuestro repositorio de Github sólo hay que pulsar en la pestaña de wiki dentro de la página de nuestro proyecto, para añadir una nueva página de documentación. Se puede añadir imágenes incluidas en alguna de las carpetas del repositorio, añadir enlaces, menús laterales e incluso pies de páginas.
La página que se llame Home será por defecto la página de inicio de nuestra documentación. No he encontrado la manera de ordenar las páginas en el menú lateral que sale por defecto. Por eso, para mantener una especie de índice, suelo incluir una tabla de contenidos en mi página de inicio, con enlaces a cada una de las páginas. Por supuesto, se puede crear una barra lateral ad hoc, y en lla sí se podrá configurar el orden de los enlaces, pero estará situado debajo del menú lateral por defecto, el cual no se ocultar a día de hoy.
Las wikis de Github son fáciles de usar y probablemente lo suficientemente potentes para la mayor parte de los proyectos, pero a veces resuta necesario poder contar con una presentación más vistosa o con un alojamiento para la documentación al margen del repositorio de código de Github. Ahí es donde ReadTheDocs entra en juego. ReadTheDocs puede conectarse mediante webhooks al repositorio de Github, de manera que los pushes al repositorio disparen automáticamente el proceso de compilación de la documentación. Además, permite mantener varias versiones de la documentación, lo que es bastante útil si el uso de la aplicación difiere según la versión que este utilizando el usuario. También permite crear ficheros PDF o ePUB con la documentación generada para que esté disponible para su descarga.
Una vez registrado en ReadTheDocs hay que dirigirse a Settings--> Connected Services para enlazar la cuenta de ReadTheDocs que la que se use en Github o Bitbucket. Tras eso hay que ir a My Projects --> Import a Project para crea la conexión con el el repositorio específico donde se encuentra la documentación. Se nos preguntará qué nombre ponerle al proyecto de documentación. Ese nombre se usará para asignarle una URL pública al proyecto.
Sin embargo, hay que ser conscientes de que no se podrá cambiar el nombre del proyecto más tarde (como mucho podremos borrar el proyecto y volver a crearlo con otro nombre). ¿Por qué querríamos cambiarle el nombre al proyecto? puede que se nos ocurra un nombre mejor o que alguno de los caracteres utilizados de problemas, por ejemplo cree un proyecto llamado "vdist-" (ojo al guión final, que no es un error), y después de algún tiempo me di cuenta de que la url que se había generaro (http://vdist-.readthedocs.io/en/latest/) no funcionaba bien desde todos los navegadores y todas las localizaciones (mi navegador chrome de PC se conectaba bien a la página pero el navegador de my smartphone me daba un mensaje de error de DNS). Recree el proyecto con el nombre "vdistdocs" y problema resuelto.
No se cómo es en Bitbucket, pero en Github se deben permitir las notificaciones por webhooks a ReadTheDocs a través de la página Settings--> Webhooks de Github.
Cuano nuestro proyecto aparezca en la página de proyectos podremos pulsa él para entrar en su configuración. Allí se pueden fijar el tipo de lenguaje de marcado usado en la documentación. Markdown está explícitamente incluido entre las opciones y RST es cualquiera de las opciones que hacen referencia a Sphinx. En Advanced Settings se puede fijar si queremos crear una versión en PDF o ePUB en cada una de las compilaciones, así como si queremos que la documentación compilada esté públicamente disponible. Aparte de eso, ReadTheDocs tiene un montón de posibilidades avanzadas que podemos activar a través de su página de configuración, pero creo que la configuración más sencilla para empezar a andar se limita a los parámetros que he mencionado hasta el momento.
Para mi, la parte más dura de configurar ReadTheDocs fue averiguar qué estructura de ficheros esperaba para poder compilarlos correctamente. Hay dos posibles configuraciones dependiendo de si nuestra documentación es Markdown o RST.
Para documentación en Markdown deberíamos incluir un fichero mkdocs.yml en nuestro repositorio. Ese fichero contiene la configuración básica necesaria para compilar nuestra documentación. Podemos ver un ejemplo de este tipo de fichero en el que se usa en el proyecto vdist:
Como se puede ver, el fichero mkdocs.yml es muy sencillo. Sólo contiene el nombre de proyecto, que se mostrará como el título de la página de documentación, el tema visual a aplicar a la configuración compilada y una tabla de contenidos enlazando a las páginas de markdown de cada sección. Esa tabla de contenidos es la que aparecerá en el menú de la izquierda cuando se compile la documentación.
Usando el fichero mkdocs como referencia, ReadTheDocs buscará en las carpetas que se llamen doc o docs en nuestro repositorio para compilar su contenido, y si no encuentra ninguna de esas carpetas buscará desde la raíz del repositorio.
Para la documentación en RST el proceso es similar, pero el fichero que se usa como referencia es el conf.py generado por Sphinx. Aquí hay un buen tutorial sobre cómo configurar sphinx para crear ficheros que puedan ser importados por ReadTheDocs.
El único problema que he encontrado no está exactamente relacionado con él sino con su compatibilidad con documentación en RST generada para ser utilizada en la wiki de Github. El problema es que la wiki de Github usa un formato para los enlaces distinto del de ReadTheDocs. Hay un buen hilo en starckoverflow sobre el tema. Hay que ser consciente de lo anterior para estructurar de antemano la documentación con el workaround explicado en dicho hilo, si queremos publicar tanto en Github como en ReadTheDocs.
Para alojar la documentación web generada se puede usar cualquier servidor web pero hay muchos servicios gratuitos para proyectos de código abierto. Aquí vamos a revisar las wikis de Github y el servicio de ReadTheDocs.
Github wikis
La opción más sencilla es Github, que permite alojar documentación a través de sus páginas de wiki.
Dichas páginas permiten utilizar tanto Markdown como RST, así como editar las páginas tanto directamente con un navegador como descargándolas como un repositorio git, aparte del de nuestro código fuente. Sólo hay que tener en cuenta que aunque se pueden hacer ramas (branches) en el repositorio de nuestra documentación, sólo serán visibles los pushes a la rama master.
La URL para clonar el reposiorio de la wiki se puede ver en la pestaña de Github referente a la wiki. Además hay que tener en cuenta que a la hora de hacer pushes los fichero añadidos deberán tener una extensión coherente con el lenguaje de marcado utilizado: .md para Markdown o .rst para reStructuredText.
Además. la edición de la documentación puede realizarse colaborativamente asignando permisos a diferentes usuarios.
Para crear una nueva wiki en nuestro repositorio de Github sólo hay que pulsar en la pestaña de wiki dentro de la página de nuestro proyecto, para añadir una nueva página de documentación. Se puede añadir imágenes incluidas en alguna de las carpetas del repositorio, añadir enlaces, menús laterales e incluso pies de páginas.
La página que se llame Home será por defecto la página de inicio de nuestra documentación. No he encontrado la manera de ordenar las páginas en el menú lateral que sale por defecto. Por eso, para mantener una especie de índice, suelo incluir una tabla de contenidos en mi página de inicio, con enlaces a cada una de las páginas. Por supuesto, se puede crear una barra lateral ad hoc, y en lla sí se podrá configurar el orden de los enlaces, pero estará situado debajo del menú lateral por defecto, el cual no se ocultar a día de hoy.
ReadTheDocs
Las wikis de Github son fáciles de usar y probablemente lo suficientemente potentes para la mayor parte de los proyectos, pero a veces resuta necesario poder contar con una presentación más vistosa o con un alojamiento para la documentación al margen del repositorio de código de Github. Ahí es donde ReadTheDocs entra en juego. ReadTheDocs puede conectarse mediante webhooks al repositorio de Github, de manera que los pushes al repositorio disparen automáticamente el proceso de compilación de la documentación. Además, permite mantener varias versiones de la documentación, lo que es bastante útil si el uso de la aplicación difiere según la versión que este utilizando el usuario. También permite crear ficheros PDF o ePUB con la documentación generada para que esté disponible para su descarga.Una vez registrado en ReadTheDocs hay que dirigirse a Settings--> Connected Services para enlazar la cuenta de ReadTheDocs que la que se use en Github o Bitbucket. Tras eso hay que ir a My Projects --> Import a Project para crea la conexión con el el repositorio específico donde se encuentra la documentación. Se nos preguntará qué nombre ponerle al proyecto de documentación. Ese nombre se usará para asignarle una URL pública al proyecto.
Sin embargo, hay que ser conscientes de que no se podrá cambiar el nombre del proyecto más tarde (como mucho podremos borrar el proyecto y volver a crearlo con otro nombre). ¿Por qué querríamos cambiarle el nombre al proyecto? puede que se nos ocurra un nombre mejor o que alguno de los caracteres utilizados de problemas, por ejemplo cree un proyecto llamado "vdist-" (ojo al guión final, que no es un error), y después de algún tiempo me di cuenta de que la url que se había generaro (http://vdist-.readthedocs.io/en/latest/) no funcionaba bien desde todos los navegadores y todas las localizaciones (mi navegador chrome de PC se conectaba bien a la página pero el navegador de my smartphone me daba un mensaje de error de DNS). Recree el proyecto con el nombre "vdistdocs" y problema resuelto.
No se cómo es en Bitbucket, pero en Github se deben permitir las notificaciones por webhooks a ReadTheDocs a través de la página Settings--> Webhooks de Github.
Cuano nuestro proyecto aparezca en la página de proyectos podremos pulsa él para entrar en su configuración. Allí se pueden fijar el tipo de lenguaje de marcado usado en la documentación. Markdown está explícitamente incluido entre las opciones y RST es cualquiera de las opciones que hacen referencia a Sphinx. En Advanced Settings se puede fijar si queremos crear una versión en PDF o ePUB en cada una de las compilaciones, así como si queremos que la documentación compilada esté públicamente disponible. Aparte de eso, ReadTheDocs tiene un montón de posibilidades avanzadas que podemos activar a través de su página de configuración, pero creo que la configuración más sencilla para empezar a andar se limita a los parámetros que he mencionado hasta el momento.
Para mi, la parte más dura de configurar ReadTheDocs fue averiguar qué estructura de ficheros esperaba para poder compilarlos correctamente. Hay dos posibles configuraciones dependiendo de si nuestra documentación es Markdown o RST.
Para documentación en Markdown deberíamos incluir un fichero mkdocs.yml en nuestro repositorio. Ese fichero contiene la configuración básica necesaria para compilar nuestra documentación. Podemos ver un ejemplo de este tipo de fichero en el que se usa en el proyecto vdist:
site_name: vdist
theme: readthedocs
pages:
- [index.md, Home]
- [whatisvdist.md, What is vdist]
- [usecases.md, Use cases]
- [howtoinstall.md, How to install]
- [howtouse.md, How to use]
- [howtocustomize.md, How to customize]
- [buildenvironment.md, Optimizing your build environment]
- [qanda.md, Questions and Answers]
- [howtocontribute.md, How to contribute]
- [releasenotes.md, Release notes]
- [roadmap.md, Development roadmap]
Como se puede ver, el fichero mkdocs.yml es muy sencillo. Sólo contiene el nombre de proyecto, que se mostrará como el título de la página de documentación, el tema visual a aplicar a la configuración compilada y una tabla de contenidos enlazando a las páginas de markdown de cada sección. Esa tabla de contenidos es la que aparecerá en el menú de la izquierda cuando se compile la documentación.
Usando el fichero mkdocs como referencia, ReadTheDocs buscará en las carpetas que se llamen doc o docs en nuestro repositorio para compilar su contenido, y si no encuentra ninguna de esas carpetas buscará desde la raíz del repositorio.
Para la documentación en RST el proceso es similar, pero el fichero que se usa como referencia es el conf.py generado por Sphinx. Aquí hay un buen tutorial sobre cómo configurar sphinx para crear ficheros que puedan ser importados por ReadTheDocs.
El único problema que he encontrado no está exactamente relacionado con él sino con su compatibilidad con documentación en RST generada para ser utilizada en la wiki de Github. El problema es que la wiki de Github usa un formato para los enlaces distinto del de ReadTheDocs. Hay un buen hilo en starckoverflow sobre el tema. Hay que ser consciente de lo anterior para estructurar de antemano la documentación con el workaround explicado en dicho hilo, si queremos publicar tanto en Github como en ReadTheDocs.
