Les beceroles de Sphinx per a col·laboradors d’ArviZ i PyMC

Fig. 1 Sphinx és un generador de documentació

Sphinx pren contingut de text en brut escrit amb un llenguatge de marques, i el tradueix i el renderitza en un format de sortida ric com html o pdf.

El llenguatge de marques natiu en Sphinx és rST, però també és possible utilitzar MyST, un superconjunt de Markdown gràcies al projecte executablebooks.

Fig. 2 esbossa el procés pel qual sphinx genera documentació. No et preocupis si les coses encara no tenen gaire sentit. El concepte clau s’explicarà, ja que són necessaris i també es proporcionaran referències per a lectura addicional en les properes pàgines.

Fig. 2 Procés de generació de documentació amb Sphinx.

ArviZ i PyMC utilitzen tant rST com MyST, que es poden combinar sense problemes dins de la mateixa documentació, però la major part del contingut està escrit en MyST, amb rST utilitzat gairebé exclusivament per a docstrings.

Per què MyST? MyST és un superconjunt de Markdown, per tant Markdown pur també són marques vàlides en MyST. Markdown és el llenguatge de marques més comú avui en dia i tant desenvolupadors com usuaris d’ArviZ i PyMC estan familiaritzats amb ell degut a llocs com GitHub o Discourse. A més, el Markdown és el llenguatge de marques utilitzat en els quaderns Jupyter. Usar MyST també ens permet treballar indistintament en fitxers .md o .ipynb.