Cambio de la documentación de Sphinx a la de MkDocs: ¿qué gané y qué perdí?  |  de Kay Jan Wong |  febrero de 2024

Guía para realizar este cambio y comparación entre ellos

Foto de melanfolia en Unsplash
Foto por melanfolia en desempaquetar

“Un proyecto es tan bueno como su documentación”: una cita de mi serie anterior de artículos de tres partes que enfatiza la importancia de la documentación. Desde entonces aprendí que existen diferentes tipos de documentación, siendo las más comunes:

  1. Documentación técnica: Describe los aspectos técnicos del funcionamiento interno del proyecto, puede ser documentación de proceso o documentación de producto.
  2. Documentación comercial: Describir qué problemas comerciales resuelve u objetivos comerciales cumplidos.

Existe un tipo de documentación que está en el medio, estos son manuales, guías y tutoriales. Esto es especialmente importante si quieres usuarios técnicos para trabajar con o utilizar su proyecto, o usuarios empresariales para entender su proyecto y conseguir aceptación.

A medida que la documentación se vuelve más compleja y con más contenido, puede resultar complicado mostrarla en un formato fácil de usar y legible. Por ejemplo, los tutoriales no deben estar integrados en la documentación técnica y, idealmente, debería haber una pestaña o sección de navegación separada entre ellos.

Esto me impulsó a explorar más temas de Sphinx para hacer mi documentación más bonita y poder manejar más información. Terminé sintiéndome atraído por Material de esfinge y Esfinge-Inmaterial temas que implementan el tema Material de MkDocs. Después de muchos ajustes y aún sin obtener los resultados que quería, cambié a MkDocs y finalmente entendí el revuelo sobre MkDocs.

Después de haber probado varios métodos y temas de documentación, intentaré compararlos, centrándome en los características ganadas y perdidas desde el cambio de Sphinx a MkDocs. Finalmente, este artículo terminará con configuraciones importantes de MkDocs que se pueden incorporar para obtener una documentación más óptima.

Nota: Si está interesado, este es el enlace a mi documentación realizada con el tema Sphinx-Material, y este es el enlace a la misma documentación hecha con MkDocs 🙂