Readthedocs
"Read the Docs" es una plataforma de documentación que facilita la creación, alojamiento y mantenimiento de documentación técnica de proyectos de software. Está diseñada para integrar con sistemas de control de versiones como Git y Mercurial, permitiendo que la documentación se genere automáticamente a partir del código fuente.
Aquí están algunas características clave de Read the Docs:
-
Generación Automática de Documentación: La plataforma puede generar documentación automáticamente utilizando herramientas como Sphinx, que es muy popular para la documentación de proyectos en Python.
-
Alojamiento de Documentación: Ofrece alojamiento gratuito para la documentación, lo que elimina la necesidad de configurar y mantener un servidor propio para este propósito.
-
Versionado: Permite mantener múltiples versiones de la documentación, lo cual es útil cuando se necesita documentar diferentes versiones de un software.
-
Integraci ón con Control de Versiones: Se integra con repositorios de código en servicios como GitHub, GitLab y Bitbucket. Esto facilita la actualización automática de la documentación cada vez que se realizan cambios en el código.
-
Internacionalización y Localización: Soporta la creación de documentación en múltiples idiomas, lo cual es beneficioso para proyectos con una audiencia global.
-
Temas Personalizables: Ofrece una variedad de temas para la presentación de la documentación y permite la personalización de estos temas para ajustarse a las necesidades del proyecto.
En resumen, Read the Docs es una herramienta poderosa y conveniente para desarrolladores que buscan una solución eficiente y escalable para la documentación de sus proyectos.
Creación de la documentación
Sphinx
Sphinx es una herramienta poderosa para generar documentación en Python, y aunque su formato principal de entrada es reStructuredText (reST), es posible utilizar Markdown con algunas configuraciones adicionales. Aquí te explico cómo puedes hacerlo:
Instalación
-
Instala Sphinx y el soporte para Markdown: Necesitarás instalar Sphinx y algunas extensiones para soportar Markdown. Puedes hacerlo con pip:
pip install sphinx recommonmark
Además, si quieres soporte avanzado para Markdown, puedes instalar
myst-parser
:pip install myst-parser
Configuración del proyecto
-
Inicializa un proyecto de Sphinx: Si aún no tienes un proyecto de Sphinx, puedes inicializar uno con:
sphinx-quickstart
Esto te guiará a través de una serie de preguntas para configurar tu proyecto. Para propósitos básicos, puedes aceptar los valores predeterminados.
-
Configura Sphinx para usar Markdown: Abre el archivo
conf.py
que Sphinx generó y añade las siguientes configuraciones:Para
recommonmark
:# conf.py
# Agrega estas líneas para permitir el soporte de Markdown
extensions = [
'recommonmark'
]
# Opcionalmente, añade estas configuraciones adicionales
from recommonmark.transform import AutoStructify
def setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)Para
myst-parser
:# conf.py
# Agrega esta línea para usar myst-parser
extensions = [
'myst_parser'
]
# Opcionalmente, configura MyST-Parser
myst_enable_extensions = [
"dollarmath",
"amsmath",
"deflist",
"html_image",
"colon_fence",
]
Creación de Documentación en Markdown
-
Crea archivos Markdown: Crea archivos
.md
en tu directorio de documentación. Por ejemplo, puedes crear un archivoindex.md
:# Bienvenido a la Documentación de Mi Proyecto
Este es el archivo de inicio de la documentación.
## Sección 1
Aquí va el contenido de la sección 1.
## Sección 2
Aquí va el contenido de la sección 2. -
Referencia los archivos Markdown en tu archivo de índice: Asegúrate de que tu
index.rst
(oindex.md
si estás usando MyST-Parser) haga referencia a los archivos Markdown. Si estás usandoindex.rst
, puedes hacerlo así:.. toctree::
:maxdepth: 2
:caption: Contenido
index.mdSi estás usando
index.md
(con MyST-Parser), puedes referenciar otros archivos Markdown directamente:```{toctree}
---
maxdepth: 2
caption: Contenido
---
index.md
otro_archivo.md
Generar la documentación
-
Genera la documentación: Ejecuta el siguiente comando para construir la documentación:
make html
Este comando generará la documentación en formato HTML en el directorio
_build/html
.
Mostrar la documentación
Para revisar la documentación generada por Sphinx en un servidor local, puedes seguir estos pasos:
Paso 1: Generar la documentación HTML
Primero, asegúrate de que has generado la documentación en formato HTML. Desde la raíz de tu proyecto de Sphinx, ejecuta:
make html
Esto generará la documentación en el directorio _build/html
.
Paso 2: Servir la documentación localmente
Puedes utilizar varios métodos para servir la documentación HTML localmente. Aquí te muestro algunas opciones comunes:
Opción 1: Usar Python's HTTP Server
Python tiene un servidor HTTP incorporado que es muy fácil de usar. Desde la raíz del directorio _build/html
, ejecuta:
cd _build/html
python -m http.server
Esto iniciará un servidor HTTP en el puerto 8000. Podrás acceder a tu documentación abriendo un navegador web y navegando a http://localhost:8000
.
Opción 2: Usar live-server
para recarga en vivo
Si prefieres una experiencia de recarga en vivo (donde la página se actualiza automáticamente cuando realizas cambios en los archivos), puedes usar live-server
. Primero, instala live-server
usando npm:
npm install -g live-server
Luego, desde la raíz del directorio _build/html
, ejecuta:
cd _build/html
live-server
Esto también iniciará un servidor HTTP, usualmente en el puerto 8080, y puedes acceder a tu documentación en http://localhost:8080
. La ventaja de live-server
es que recargará automáticamente la página cuando detecte cambios en los archivos.
Paso 3: Visualizar la documentación en el navegador
Independientemente del método que hayas elegido, abre tu navegador y navega a la URL correspondiente (por ejemplo, http://localhost:8000
o http://localhost:8080
). Deberías ver tu documentación generada por Sphinx.
Resumen
- Genera la documentación HTML:
make html
. - Inicia un servidor local:
- Para un servidor básico:
python -m http.server
desde_build/html
. - Para recarga en vivo:
live-server
desde_build/html
.
- Para un servidor básico:
- Accede a tu documentación: Abre
http://localhost:8000
(ohttp://localhost:8080
si usaslive-server
) en tu navegador.
Estos métodos te permitirán revisar y verificar tu documentación localmente antes de publicarla.
Agregando otros temas
Cambiar el tema de la documentación generada por Sphinx es un proceso sencillo. Sphinx viene con varios temas preinstalados, pero también puedes instalar y usar temas personalizados. A continuación, te explico cómo cambiar el tema de tu documentación.
Paso 1: Editar conf.py
El archivo conf.py
es donde configuras el tema de tu documentación. Abre conf.py
y busca la variable html_theme
. Aquí puedes establecer el tema que deseas usar.
Usar un tema preinstalado
Sphinx incluye varios temas preinstalados, como alabaster
(el tema por defecto), classic
, sphinx_rtd_theme
(el tema de la Documentación de Read the Docs), entre otros.
Por ejemplo, para usar el tema sphinx_rtd_theme
:
-
Instala el tema (si aún no está instalado):
pip install sphinx-rtd-theme
-
Edita
conf.py
y establecehtml_theme
asphinx_rtd_theme
:# conf.py
html_theme = 'sphinx_rtd_theme'
Usar un tema personalizado
Si deseas usar un tema personalizado que no viene preinstalado con Sphinx, primero debes instalarlo. Hay muchos temas disponibles en PyPI. Por ejemplo, puedes instalar el tema sphinx_material
:
-
Instala el tema:
pip install sphinx_material
-
Edita
conf.py
y establecehtml_theme
asphinx_material
:# conf.py
html_theme = 'sphinx_material' -
Configura las opciones del tema (opcional):
Muchos temas personalizados tienen opciones específicas que puedes configurar. Por ejemplo, para
sphinx_material
, puedes añadir configuraciones adicionales:# conf.py
html_theme = 'sphinx_material'
# Configuraciones del tema material
html_theme_options = {
'nav_title': 'Mi Proyecto',
'color_primary': 'deep-purple',
'color_accent': 'blue',
'repo_url': 'https://github.com/tu_usuario/tu_repositorio',
'repo_name': 'tu_repositorio',
'globaltoc_depth': 3,
'globaltoc_collapse': True,
'globaltoc_includehidden': True,
}
Paso 2: Añadir archivos estáticos y plantillas (opcional)
Algunos temas permiten personalizar aún más la apariencia mediante el uso de archivos estáticos y plantillas personalizadas. Puedes colocar estos archivos en las carpetas _static
y _templates
respectivamente.
-
Archivos estáticos: coloca archivos CSS, JS o imágenes personalizadas en
_static
. -
Plantillas personalizadas: coloca plantillas HTML personalizadas en
_templates
.
Paso 3: Reconstruir la documentación
Después de hacer los cambios en conf.py
, reconstruye la documentación para ver los cambios reflejados:
make html
Ejemplo completo de conf.py
con sphinx_rtd_theme
Aquí tienes un ejemplo completo de conf.py
configurado para usar el tema sphinx_rtd_theme
:
# conf.py
# -- Project information -----------------------------------------------------
project = 'Mi Proyecto'
author = 'Tu Nombre'
version = '1.0'
release = '1.0.0'
# -- General configuration ---------------------------------------------------
extensions = [
'myst_parser',
]
# Configuración opcional para MyST-Parser
myst_enable_extensions = [
"dollarmath",
"amsmath",
"deflist",
"html_image",
"colon_fence",
]
templates_path = ['_templates']
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
Resumen
- Editar
conf.py
para cambiar el tema a uno preinstalado o personalizado. - Instalar el tema (si es necesario).
- Configurar opciones del tema si el tema lo permite.
- Reconstruir la documentación para aplicar los cambios.
Siguiendo estos pasos, podrás cambiar y personalizar el tema de tu documentación generada por Sphinx de acuerdo a tus necesidades.
Publicar el código en Readthedocs
Para subir tu documentación a Read the Docs en Python, sigue estos pasos:
-
Prepara tu documentación:
- Escribe tu documentación utilizando Sphinx, que es la herramienta recomendada para crear documentación en Read the Docs.
- Asegúrate de tener un archivo de configuración
conf.py
y un archivo de índiceindex.rst
en tu proyecto.
-
Instala Sphinx: Si aún no tienes Sphinx instalado, puedes instalarlo utilizando pip:
pip install sphinx
-
Genera la documentación: Navega a la raíz de tu proyecto y ejecuta el comando
sphinx-quickstart
para configurar Sphinx. Sigue las instrucciones para crear los archivos iniciales necesarios.sphinx-quickstart
-
Escribe tu documentación: Edita los archivos
.rst
en el directoriosource
generado por Sphinx. Aquí es donde escribirás la mayor parte de tu documentación. -
Configura tu proyecto en Read the Docs:
- Crea una cuenta en Read the Docs.
- Conecta tu cuenta de Read the Docs con tu repositorio (por ejemplo, GitHub, GitLab, Bitbucket) donde está alojado tu proyecto.
- En Read the Docs, crea un nuevo proyecto y selecciona el repositorio que contiene tu documentación.
-
Configura el archivo
.readthedocs.yml
: Coloca un archivo.readthedocs.yml
en la raíz de tu repositorio para definir la configuración de construcción de Read the Docs. Un ejemplo básico podría ser:version: 2
sphinx:
configuration: docs/conf.py
python:
version: 3.8
install:
- requirements: docs/requirements.txtversion
: Define la versión de configuración de Read the Docs.sphinx.configuration
: Indica la ruta al archivo de configuraciónconf.py
de Sphinx.python.version
: Especifica la versión de Python a usar.python.install.requirements
: Especifica un archivo de requisitos donde defines las dependencias necesarias para construir tu documentación.
-
Sube tu proyecto al repositorio: Asegúrate de que todos los archivos necesarios, incluidos los de configuración y documentación, estén en el repositorio. Luego, haz push a tu repositorio.
-
Construye la documentación en Read the Docs: Una vez que tu proyecto esté configurado y enlazado con Read the Docs, cada vez que hagas un commit en tu repositorio, Read the Docs automáticamente reconstruirá y actualizará tu documentación.
-
Revisa y ajusta:
- Si hay errores, Read the Docs te mostrará registros detallados de la construcción donde puedes ver qué salió mal.
- Ajusta tu configuración y los archivos de documentación según sea necesario y vuelve a hacer commit y push.
Aquí tienes una guía más detallada y específica en la documentación oficial de Read the Docs: Read the Docs: Introducción.