Sintaxis de documentación: markdown vs. myST vs. rst.#

Hay tres sintaxis comúnes para crear documentación en Python:

  1. markdown: Markdown es una sintaxis de texto plano que es fácil aprender. Es la sintaxis por defecto para Jupyter Notebooks. Hay herramientas que puedes usar con Sphinx que permiten renderizar markdown como HTML. Sin embargo, usar markdown para escribir documentación tiene limitaciones. Por ejemplo, si deseas añadir referencias, tarjetas de colores, u otros elementos personalizados a tu documentación, necesitarás usar myST o rST.

  2. rST (ReStructured Text):. rST es la sintaxis nativa para Sphinx. rST ha sido la sintaxis por defecto para documentación durante muchos años. Sin embargo, recientemente myST ha aumentado en popularidad para convertirse en la herramienta favorita para documentación gracias a sflexibilidad.

  3. myST: myST is a combination of markdown and rST syntax. It is a nice option if you are comfortable writing markdown. myst is preferred by many because it offers both the rich functionality of rST combined with a simple-to-write markdown syntax.

Aunque puedas elegir cualquiera sintaxis listado arriba, sugerimos que usas myST porque:

  • Es una sintaxis más simple y, por lo tanto más facil de aprender;

  • Esta simplicidad hará más fácil que más gente contribuya a tu documentación.

  • La mayoría de los archivos de texto de tus paquetes principales de Python, como el archivo README.md, ya están en formato .md.

  • GitHub y Jupyter Notebooks apoyan markdown, por lo que son más utilizados en el ecosistema científico.

Truco

Si no estás seguro sobre si utilizar myST o rst, puede que encuentres que myST es más fácil para contribuciones de más gente.