En estos días me he visto en la necesidad de consultar mucha bibliografía de Django, desgraciadamente la versión que poseo es la 1.11 (super vieja) y la documentación que trae está en formato de texto plano reestructurado, con posibilidad de generarla a HTML usando la herramienta Sphinx. Según Google Sphinx es:
Un software generador de documentación que convierte ficheros reStructuredText en sitios web HTML y otros formatos, incluyendo PDF, EPub y man.
Conociendo esto procedemos entonces a instalarlo desde el repositorio (uso Xenial)
$ sudo apt install python-sphinx
tiene algunas dependencias pero en general se descarga bien rápido.
Una vez instalado Sphinx en nuestro sistema, procedemos a movernos hacia el directorio docs de la carpeta de instalación de Django (o X software con la documentación en formato de texto plano reestructurado)
y desde ahí invocamos la conversión:
$ sudo make html
Acá está la salida en mi terminal (sin tantos warnings.. en mi caso tuve muuchos warnings) y resumida:
dcruz@genesis:~/Descargas/Django-1.11/docs$ sudo make html
[sudo] password for dcruz:
sphinx-build -b djangohtml -n -d _build/doctrees -D language=es_ES . _build/html
Running Sphinx v1.3.6
making output directory...
A Translator for the djangohtml builder is changed.
A Translator for the json builder is changed.
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] topics/testing/tools
unittest.TestCase.assertTrue
unittest.skipIf
generating indices... genindex py-modindex
highlighting module code... [100%] django.db.models.fields.related
writing additional pages... search
copying images... [ 4%] ref/contrib/admin/_images/adding-actions-to-the-modeladcopying images... [ 37%] topics/testing/_images/django_unittest_classes_hierarchcopying images... [ 79%] ref/contrib/admin/_images/actions-as-modeladmin-methodscopying images... [100%] intro/_images/admin14t.png
copying downloadable files... [100%] /home/dcruz/Descargas/Django-1.11/docs/ref/contrib/gis/install/geodjango_setup.bat
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
writing templatebuiltins.js...
build succeeded, 445 warnings.
Build finished. The HTML pages are in _build/html.
Y listo, el sitio completo se ubica en la carpeta _build, les dejo una captura de pantalla de la documentación generada en HTML, bueno, les debo la captura no encuentro como subir imágenes.
¿Te resultó interesante? Compártelo ...
Pensé que el artículo iba a ser un tutorial de Sphinx o algo así. ¿Por qué ejecutas make html con sudo? No me parece que haga falta. Por cierto, la documentación de django está disponible como html y como pdf desde el sitio del proyecto ( si tienes acceso a internet).
Django 1.11 no es «viejo», es la versión LTS actual y una buena elección.
Finalmente, yo uso Sphinx para generar la documentación de mis proyectos hechos con Django, pero para conversión general de documentos (sobre todo para generar presentaciones y pdfs a partir de markdown) recomiendo Pandoc.
Crees que pasara tanto trabajo convirtiendo a HTML si tuviera Internet? creo que me dio error al ejecutar make sin privilegios.
Vaya, escribir acá es un problema jaja, te caen a balas al instante..
1.11 No es vieja, es la version LTS, asi que es la aconsejable
Que malo no tener internet :S