tractatus@lapipaplena:/# _

sphinx

Generador de documentación o una herramienta que traduce un conjunto de archivos fuente de texto plano a varios formatos de salida, generando automáticamente referencias cruzadas, índices, etc. Sphinx se centra en la documentación, en particular la documentación manuscrita; sin embargo, también puede utilizarse para generar blogs [ver ablog], páginas de inicio e incluso libros. El proceso inicial básico es:

$ mkdir bl_sphinx

crear el directorio de origen

$ cd bl_sphinx

entrar en él

$ sphinx-quickstart

hace algunas pareguntas y crea la estructura del directorio con el archivo de configuración conf.py

$ ls

muestra del contenido del directorio creado

_build/ _static/ _templates/ conf.py index.rst make.bat Makefile

Nota.- Nunca editar los archivos del directorio _build ni los .html, siempre las entradas .rst y el index.rst a parte del conf.py

Las "entradas" [posts], se crean en el directorio origen [el raiz], junto a index.rst.

1.-

Crear una entrada de blog

$ cd bl_sphinx

el sourcedir

$ nano entrada1.rst

Mi primera entrada

==================

Publicado el 12 de febrero de 2026

Linux es un sistema genial.

Decirle a Sphinx que lo incluya sin la extensión .rst

$ nano index.rst

...

.. toctree::

:maxdepth: 2

:caption: Contents:

entrada1

...

Una configuración sin tener que entrar los nuevos posts podría ser:

4 nano index.rst

.. postlist::

:list-style: circle

:category: Manual

:format: {date} — {title}

:sort:

$ make html

compila la nueva entrada y los html se instalan en _build/html [outputdir]

$ firefox _build/html/index.html

ver el resultado con el navegador

$ make clean

para eliminar un post o modificar alguno antiguo