Artículo
Ricardo Paiva · Oct 28, 2021 Lectura de 2 min

Generadores de documentación estática

¡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:

  1. Documentación obsoleta,
  2. Documentación no interactiva y difícil de consultar,
  3. Diseño poco amigable y que no se adhiere a HTML,
  4. Imposibilidad de personalizar el diseño de los documentos,
  5. Imposibilidad de tener documentación en HTML 5 online y offline.
  6. 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   

0
0 85
Debate (0)2
Inicie sesión o regístrese para continuar