Generadores de documentación estática

Artículo

Ricardo Paiva · 28 oct, 2021 Lectura de 2 min

Open Exchange

¡Hola comunidad!

En el pasado, la documentación técnica del código fuente y de los productos de software se generaba en archivos chm, pdf y generadores de documentación de los propios lenguajes de programación. Este enfoque antiguo tenía las siguientes limitaciones:

Documentación obsoleta,
Documentación no interactiva y difícil de consultar,
Diseño poco amigable y que no se adhiere a HTML,
Imposibilidad de personalizar el diseño de los documentos,
Imposibilidad de tener documentación en HTML 5 online y offline.
Falta de soporte a Markdown.

Hoy en día, existen varias soluciones de generación de documentación que producen Portales de Documentación Web muy atractivos, interactivos y con opciones estáticas y dinámicas, con soporte total para HTML 5 y más recientemente Markdown.

Consulta la tabla con las opciones de código abierto más populares:

Documentation Product	Stars
MkDocs Github Repo: https://github.com/mkdocs/mkdocs Static and dynamic documentation generation Simple and lightweight and built in Python Smart full-text search box Multiple themes and plug-ins Support to Markdown and HTML Integration with Git pages Extensible using Python SPA architecture	11.4k
Docsify Github Repo: https://github.com/docsifyjs/docsify No statically built html files Simple and lightweight (~21kB gzipped) Smart full-text search plugin Multiple themes Useful plugin API Compatible with IE11 Support SSR Support embedded files	16.5k
Docusaurus Github: https://github.com/facebook/docusaurus/ Powered by Markdown Built Using React Ready for Translations Document Versioning Document Search Quick Setup	21.4k
Slate Github: https://github.com/slatedocs/slate Clean, intuitive design Single page documentation Markdown support Out-of-the-box syntax highlighting Write code samples in multiple languages Automatic, smoothly scrolling table of contents Documentation is editable by users via Github RTL Support	31.9k
GitBook https://www.gitbook.com/ Clean, intuitive design Collaborative work/text edition Support to drafts and versioning Single page documentation Markdown support Out-of-the-box syntax highlighting Write code samples in multiple languages Automatic, smoothly scrolling table of contents The better integration with Github Multiple output formats (PDF, HTML5, epub,etc.) Cloud hosting, with free plans to personal projects and paid plans to business use cases	500,000 users

La aplicación IRIS Publisher, en Open Exchange, permite extraer bloques de documentación XData en HTML o Markdown y generar un sitio web con la documentación de tu app, utilizando MkDocs. Consulta las instrucciones en el siguiente artículo de esta serie:

Cómo crear el Portal de Documentación para InterSystems IRIS

Referencia:

5 free static documentation generators you must check out

Ir a la aplicación en InterSystems Open Exchange

Ir a la publicación original, escrita por @Yuri Marx