Documentación de contribución a PyMC#

Una descripción general de la documentación de PyMC#

La documentación de PyMC se genera a partir de dos repositorios de GitHub diferentes, cada uno de los cuales contiene un tipo diferente de documentación:

  • pymc: El repositorio de pymc contiene la mayor parte del contenido de referencia en forma de docstrings (cadenas adjuntas al objeto de Python que describen), algunas guías sobre la funcionalidad principal y los documentos de contribución.

  • pymc-examples: El repositorio pymc-examples contiene una colección de más de 90 notebooks con ejemplos de uso, explicaciones detalladas y tutoriales sobre PyMC.

En esta charla, nos centraremos en contribuir a pymc-examples, que contiene documentación cada vez más diversa. Comenzaremos con una descripción del recurso, sus características y cómo se relacionan con nuestros objetivos pedagógicos y luego nos sumergiremos en el uso de esas características para escribir documentación técnica clara, bonita y bien referenciada.

La idea: un libro ejecutable hecho a partir de blogs#

Prudencia

No explicaremos cómo configurar un sitio web similar, esto tomaría otra charla completa.

Daremos una descripción general de las funciones disponibles y de por qué las elegimos para luego profundizar en nuestro objetivo principal de la charla: ¿Cómo puedes, como persona que colabora a la documentación de PyMC, aprovecharlas?

Nuestra lista de deseos:

  • Fácil de escribir

  • Fácil de ejecutar, tanto al escribir páginas como al leerlas. Deberíamos poder ejecutar el código dentro de unos años.

  • Navegable a través de etiquetas y categorías

  • Se puede buscar por sí mismo y se puede buscar en la documentación de la biblioteca pymc

  • Recurso citable

  • Reconocer a las personas autoras (sin convertirlo en el foco)

  • Índice automático

  • Accesible

  • DRY: no te repitas (de sus siglas en inglés). Las cosas compartidas entre varios notebooks deben hacerse una vez cuando sea posible.

La implementación: jupyter notebook + sphinx (+ extensiones)#

  • Fácil de escribir

    • Markdown

    • suportado a través de sphinx+myst-parser

  • Fácil de ejecutar, tanto al escribir páginas como al leerlas. Deberíamos poder ejecutar el código dentro de unos años.

    • Jupyter notebook combinado con Binder e insignias de Google colab en la parte superior de cada página

    • soportado a través de sphinx+myst-nb y una plantilla html personalizada para las insignias

    • el entorno usado para ejecutarlos se almacena automaticamente gracias a la libreria watermark

  • Navegable a través de etiquetas y categorías

    • soportado a traves de sphinx+ablog

  • Se puede buscar por sí mismo y se puede buscar en la documentación de la biblioteca pymc

    • soportado a través de sphinx+pydata-sphinx-theme+readthedocs

  • Recurso citable

    • soportado a través de zenodo+una plantilla personalizada

  • Reconocer a las personas autoras (sin convertirlo en el foco)

    • soportado a través de ablog+una plantilla personalizada

  • Índice automático

    • soportado a través de sphinx+pydata-sphinx-theme

  • Accesible

    • El equipo de pydata-sphinx-theme está trabajando en la accesibilidad del tema y seguirá trabajando en ello

  • DRY: no te repitas (de sus siglas en inglés). Las cosas compartidas entre varios notebooks deben hacerse una vez cuando sea posible.

    • Citaciones centralizadas gracias a sphinx-bibtex, se referencian en la documentación usando dos palabras clave.

    • Las medallas son automáticas.

    • Las etiquetas y categorías son automáticas.

    • La tabla de contenidos se genera de forma automática

    • Las 2 últimas secciones con la información de licencias y citaciones se generan a partir de una fuente centralizada, y solo se necesitan 2 líneas por cuaderno

En resumen, gracias al trabajo de varias personas asombrosas (tanto contribuidores de PyMC con experiencia como nuevos integrantes que trabajan con nosotros mediante Outreachy y GSoD) y a los fondos que conseguimos durante PyMCon y GSoD, cambiamos la mayoría de nuestra infraestructura de documentación en los últimos 9 meses.

Desde ya puedes ver un cambio enorme:

imagen de fondo
Current style
imagen de fondo
Old style

El problema: ¿demasiada documentación?#

Nuestra infraestructura soporta todos los aspectos descritos arriba, pero solo unos cuantos cuadernos han sido actualizados para aprovecharlos. Así que, aunque podríamos tener todo eso, aún estamos lejos de lograrlo.

MyST: Texto Marcadamente Estructurado (del inglés, Markedly Structured Text)#

Como lo acabamos de decir, ya configuramos la infraestructura para todos los aspectos descritos arriba, así que no tienes que preocuparte por eso. El resto del webinar será una guía para empezar a trabajar con MyST diseñada para contribuir a los ejemplos de PyMC.

Marcado principal#

MyST es un súperconjunto de ✨✨ Markdown ✨✨. Todo lo que conoces y te encanta de Markdown funciona en MyST: cursivas, blosques de código, enlaces, encabezados, listas…

Sin embargo, Markdown tiene muchas limitaciones para la escritura técnica y para recursos que contienen muchos archivos. MyST cierra esta brecha trayendo a Markdown todas las características del texto re-estructurado, un lenguaje de marcado diseñado para escribir documentación técnica. Esto se logra extendiendo Markdown con unas cuantas expresiones personalizadas y soportando roles y directivas (las cuales cubriremos en las siguientes subsecciones).

Blancos

Los blancos se utilizan para definir anclas personalizadas que pueden referir a otras partes de la documentación a partir de roles. Generalmente van antes de los títulos de las secciones, pero también pueden apuntar a listas o a elementos específicos dentro de una lista.

Los blancos se crean colocando (target_id=) justo antes de la sección o elemento al que deseamos que apunte. Puedes ver el signo igual al final como un indicador de que haremos que el identificador de blanco sea equivalente a lo que viene después. Así pues, referenciar el id del blanco se vuelve lo mismo que referenciar un encabezado de sección o un elemento de una lista.

Matemáticas

Al igual que los cuadernos de Jupyter, MyST soporta usar el símbolo $ para escribir expresiones matemáticas de LaTeX dentro de un párrafo, y $$ para expresiones en bloque independientes. Además, a la expresiones matemáticas en bloque se les pueden asignar identificadores para referenciarlos en otras partes usando roles. Así pues:

$$
P(\theta|y) \propto P(y|\theta) P(\theta)
$$ (eq:bayes)

se renderiza así:

(1)#\[ P(\theta|y) \propto P(y|\theta) P(\theta) \]

y puede referenciarse.

Roles#

Los roles son una forma de especificar características inline arbitrarias. Su sintaxis básica es {role-name}`role-content` y se puede dividir en dos grupos: roles con referencias cruzadas y roles de formateo. El uso con referencias cruzadas es por mucho el más importante.

Roles para referencias cruzadas#

Los roles para referencias cruzadas se pueden usar de dos maneras:

{role-name}`target`

{role-name}`texto personalizado para el enlace <target>`

  • Los roles ref y numref se usan para enlazar con blancos creados manualmente, con (id)=. En las figuras ref es remplazado por el título de lo que sea que estemos enlazando. Por otra parte, numref (que no es válido para todos los tipos de objeto) se remplaza por su conteo.

  • el rol doc se usa para enlazar usando la ruta de un archivo

  • el rol term se usa para enlazar a términos definidos en nuestro glosario.

  • Referencias de dominio de Python: mod (módulo), func (función), class o meth (método) se usan para enlazar con los objetos de Python documentados en la API.

    • Estos también pueden recibir un carácter ~ antes de la ruta de importación para mostrar solo el objeto y no la ruta.

  • Citación de bibtex: cite:p y cite:t se usan para citar publicaciones científicas y decirle a sphinx que mantenga un registro de citaciones para poder generar la bibliografía de manera automática.

  • eq para blancos de ecuaciones

Ejemplos

  • {ref}`docs/idea` se renderiza como La idea: un libro ejecutable hecho a partir de blogs y apunta a un título

  • {ref}`la idea <docs/idea>` se renderiza como la idea y apunta a un título

  • {eq}`eq:bayes` se renderiza como (1) y apunta a una ecuación

  • {ref}`Elemento de lista de ejemplos de PyMC <docs/pymc-examples-point>` se renderiza como Elemento de lista de ejemplos de PyMC y apunta a un elemento de una lista por medio de un texto personalizado para el enlace. Aquí, cuando queremos enlazar a un elemento de una lista, tenemos que usar un texto personalizado, ya que sphinx no puede usar el título como tal como un texto con enlace.

  • {class}`pymc.Normal` se renderiza como pymc.Normal y apunta a la documentación de la clase Normal en PyMC

  • {class}`~pymc.Normal` se renderiza como Normal y también apunta a la documentación de la clase Normal en PyMC, pero se muestra en Normal.

  • {class}`distribución normal <pymc.Normal>` se renderiza como distribución normal y, de nuevo, también apunta a la documentación de la clase Normal en PyMC, pero mostrando texto personalizado.

  • {term}`pymc:posterior` se renderiza como posterior y apunta a la definición de posterior en el glosario.

Nota

También podemos usar referencias cruzadas con los enlaces externos. En esos casos, el blanco debe llevar antes el identificador del sitio web externo. Esto lo hacemos con nuestra referencia cruzada para el término, con la que indicamos que debería apuntar a la documentación de PyMC.

Si el blanco no existe en el sitio web actual ni se repite entre los sitios web externos que hemos configurado, nos podemos saltar este prefijo. Así pues, nos podemos saltar sin problemas los prefijos para los enlaces a objetos de python, y veremos que la ruta de importación ya es única.

Roles de formateo#

  • abbr para abreviaciones: PPL

  • bdg-<style> para medallas: caution. Referencia para estilos válidos.

  • octicon para íconos octicon:

  • fas, fab y far para íconos de Font Awesome:

Directivas#

Las directivas son una manera de especificar características arbitrarias de bloque/párrafo. Son mucho más diversas y flexibles que los roles. Su sintaxis básica es:

:::{directivename} main-argument
:kwarg1: value
:kwarg2: value

Main content of the directive, generally prose but not necessarily.
:::

De los 4 bloques (nombre, argumento, argumentos de palabra clave y contenido), solo se requiere el nombre siempre. Cada directiva tiene sus propias reglas y bloques requeridos (o incluso prohibidos en algunas ocasiones).

Figuras#

MyST proporciona una directiva figure-md donde podemos añadir imágenes con un identificador y una leyenda que se renderiza tanto en markdown puro (cuaderno no renderizado) y en el sitio web (donde luce mejor).

:::{figure-md} imposter

![imposter syndrome](imposter.jpg)

This is a caption in **Markdown**! Captions must be single paragraph.
:::
La imagen muestra dos diagramas de venn. El lado izquierdo describe el síndrome de impostor. Hay un círculo amarillo grande etiquetado como "lo que pienso que otros saben", dentro tiene un círculo pequeño azul etiquetado como "lo que sé". El lado derecho describe la realidad. El círculo azul se mantiene igualm pero aora está rodeado por muchos círculos amarillso del mismo tamaño que, cuando se combinan, cubren la misma área que el círculo amarillo grande en el diagrama anterior. Ahora, cada círculo amarillo representa lo que alguien más sabe, sin que ningún círculo sea más pequeño que los demás.

Figura 1 Image de David Whittaker#

Nos gusta mucho la imagen en Figura 1 y decidimos usarla aquí porque creemos que los ejemplos de PyMC están representados por esta imagen. Nadie en el equipo de PyMC sabe todo lo que se cubre en los ejemplos; la colección de ejemplos fue construida por los desarrolladores, usuarios expertos y los primeros contribuidores, y progresivamente empezó a cubrir más y más, justo como los círculos amarillos en el diagrama derecho.

También es un guiño a la charla de Melissa sobre sphinx, al que deberías echarle un vistazo si te interesa configurar sphinx para tu proyecto.

Advertencias#

Las advertencias son una forma de resaltar un bloque de contenido de especial relevancia. Puedes usarlas para advertencias, consejos o notas. La lista completa de estilos de avertencia está disponible en el sitio web de jupyterbook

:::{tip}
Here is an awesome tip if you use this example
:::

Truco

Usa advertencias para el contenido que no quieres que tus lectores se pierdan; incluso si solo están ojeando, es probable que se detengan en los bloques de advertencia.

¡Y mucho más!#

Hay incluso más directivas, la mayoría de las cuales no necesitas para contribuir a los ejemplos de PyMC. En la siguiente sección vamos a ver nuestra «guía de estilo de Jupyter» y cubriremos 3 directivas más que serán importantes para contribuir a los ejemplos de PyMC.

Nuestras convenciones#

Tenemos algunas convenciones adicionales para intentar asegurar que haya un estilo y formato comunes en todos los ejemplos aunque se trate de un esfuerzo colaborativo de muchas personas. Estas están detalladas en nuestra documentación, en la página Jupyter Style Guide.