Mantener un libro de documentación cuyos ejemplos de código se prueban como código real

## Tratar cada bloque de código del libro como código probado, no solo como texto El libro es una colección de ejemplos prácticos escritos como archivos markdown con bloques de código incrustados. Un arnés de pruebas de documentación recorre el árbol de fuentes, extrae cada bloque de código, lo compila y lo ejecuta, de modo que un ejemplo roto hace fallar la compilación igual que el código de aplicación roto. ### Lo que eso implica para cada edición Un ejemplo que no compila no es documentación. La prosa puede reformularse con libertad, pero cualquier cambio dentro de un bloque de código es un cambio en código fuente probado y hay que ejecutarlo con el comando de pruebas antes de proponerlo. ### Mantén sincronizados el libro renderizado y la superficie de pruebas El mismo markdown alimenta el libro renderizado y el arnés de pruebas, así que las decisiones de formato tienen carga semántica. Las anotaciones de un bloque de código deciden cómo lo trata el arnés, y las líneas ocultas para quien lee se compilan igualmente. Nunca elimines una anotación ni una línea oculta solo para que la página renderizada quede más limpia. ## Compilar, probar y ver el libro con los comandos documentados Encauza toda acción rutinaria por los comandos documentados en lugar de inventar invocaciones improvisadas, para que las ejecuciones locales coincidan con la integración continua. ### Los comandos que importan - Compilar el libro a partir de las fuentes markdown. - Ejecutar la suite completa, que son las pruebas de documentación más la pasada del corrector ortográfico. - Ejecutar solo el objetivo de pruebas de documentación cuando has cambiado un bloque de código y quieres el ciclo rápido. - Servir el libro en local con recarga en vivo mientras editas la prosa. - Compilar y probar a la vez como opción por defecto previa a la revisión. - Ejecutar el verificador de enlaces, que valida los enlaces internos y externos contra un archivo de configuración versionado en el repositorio. - Ejecutar el script del corrector ortográfico de forma interactiva y añadir las palabras nuevas legítimas al archivo de diccionario del repositorio, para que esa adición se revise junto con el cambio. ### Fija las versiones de las herramientas El generador del libro y el verificador de enlaces se instalan en versiones fijas exactas desde un único comando de instalación documentado. No actualices una herramienta en local para esquivar un fallo, porque una desviación de versión convierte un fallo reproducible en uno que solo tú puedes ver. ## Conocer las dos formas de guardar ejemplos y no subir versiones de bibliotecas compartidas Los ejemplos se prueban de una de estas dos maneras, y saber qué patrón usa un archivo determina dónde viven su código y sus dependencias. ### Patrón uno: bloques en línea probados en su sitio Los bloques de código viven directamente en el markdown dentro del árbol de fuentes. Un script de compilación recorre ese árbol en busca de archivos markdown y genera una prueba por cada bloque de código. Toda dependencia que necesite un ejemplo así debe existir ya en el manifiesto raíz. Los bloques admiten anotaciones para la edición del lenguaje y para el comportamiento, como compile-only, expected-panic y skip; el código repetitivo que quien lee no necesita se escribe como líneas con el prefijo de una almohadilla y un espacio, que el arnés compila pero el libro renderizado oculta. Este es el patrón heredado: se mantiene en funcionamiento, pero no se amplía. ### Patrón dos: paquetes independientes incluidos en el markdown El código vive en su propio paquete dentro de un directorio de código compartido, con un manifiesto independiente, y el markdown lo incorpora mediante una directiva de inclusión que apunta al archivo fuente por ruta relativa. Las inclusiones por rango de líneas permiten que una página muestre solo una parte de un archivo, que es como se mantiene el andamiaje de pruebas fuera del ejemplo renderizado. La ruta se excluye del arnés de pruebas de documentación en el script de compilación para que el código no se pruebe dos veces. Este es el patrón preferido para los ejemplos nuevos y los migrados. ### La regla de las dependencias No cambies versiones de dependencias en el manifiesto raíz. El manifiesto raíz lo comparten todos los ejemplos en línea, así que una subida de versión para satisfacer una página puede romper en silencio decenas de otras. Cuando un ejemplo necesite una dependencia más reciente, migra ese ejemplo a un paquete independiente con sus propias versiones fijadas. ## Pasar a su propio paquete el ejemplo que necesita una biblioteca más nueva Cuando haya que cambiar la versión de una dependencia, convierte los ejemplos afectados en paquetes independientes. Sigue los pasos en orden, porque cada uno deja el repositorio en un estado del que depende el paso siguiente. 1. Crea el paquete dentro del directorio de código compartido, en una carpeta con el nombre de su categoría y luego el del ejemplo, con su propio manifiesto. Hereda las dependencias compartidas del espacio de trabajo cuando sea posible, o fija versiones de forma independiente cuando divergir sea justamente el objetivo. 2. Saca el código del bloque de código markdown y llévalo al fuente del paquete: un binario por cada ejemplo ejecutable, o un módulo de biblioteca para los ejemplos de estilo biblioteca. 3. Registra el paquete en la lista de miembros del espacio de trabajo del manifiesto raíz. 4. Sustituye el código en línea del markdown por una directiva de inclusión cuya ruta relativa vaya desde la propia ubicación del archivo markdown hasta el fuente del paquete. 5. Excluye la ruta migrada del arnés de pruebas de documentación en el script de compilación. Hay dos listas de exclusión: una que toma un prefijo de directorio y elimina todo lo que hay debajo, y otra que toma un único archivo markdown. Usa la más estrecha que encaje. 6. Prueba ambos lados: ejecuta las pruebas propias del paquete nuevo y vuelve a ejecutar el objetivo de pruebas de documentación para confirmar que quitar el bloque no ha roto los ejemplos en línea restantes. Una migración que se detiene antes del paso cinco deja el ejemplo compilado dos veces, y una que se detiene antes del paso seis puede perder cobertura en silencio. ## Leer los archivos que deciden qué se compila y qué se prueba Un puñado de archivos decide qué se prueba, qué se renderiza y qué comandos existen. Léelos antes de cambiar el comportamiento, y cámbialos de forma deliberada. - El manifiesto raíz contiene las dependencias que usan los ejemplos en línea y la lista de miembros del espacio de trabajo. - El script de compilación descubre el markdown para el arnés de pruebas de documentación y lleva las dos listas de exclusión que evitan que los ejemplos migrados se prueben dos veces. - El archivo de configuración del libro controla cómo se renderiza el markdown en el libro. - La configuración de la herramienta de compilación define el alias del ejecutor de tareas en el que se apoyan los comandos documentados. - El paquete del ejecutor de tareas implementa la compilación, las pruebas y la verificación de enlaces como subcomandos, de modo que la misma lógica sirve tanto a quien contribuye como a la integración continua. Si un comando se comporta de forma distinta a como se describe aquí, trata los archivos anteriores como la fuente de verdad y corrige la descripción en vez de buscarle la vuelta. ## Escribir ejemplos completos que el lector pueda copiar y ejecutar Un ejemplo se juzga por si alguien puede copiarlo en su propio proyecto y hacerlo funcionar, no por lo corto que se ve en la página. ### Reglas de contenido - Los ejemplos son completos y compilables, no fragmentos. - Propaga los errores con el operador de propagación de errores del lenguaje en vez de provocar un pánico ante el fallo, y sigue el patrón de manejo de errores documentado del proyecto. - Evita las importaciones con comodín, para que quien lee pueda ver exactamente de qué rasgos y elementos depende el ejemplo. - Marca como compile-only los ejemplos que necesiten un servicio externo o acceso a la red, para que la suite siga siendo ejecutable sin conexión. - Oculta el código repetitivo con el prefijo de línea oculta en lugar de borrarlo, para que el ejemplo siga compilando. - Prefiere crear un paquete independiente para un ejemplo nuevo antes que añadir otra dependencia al manifiesto raíz. ### Añadir una nueva sección de primer nivel Cuando añadas una página de sección de primer nivel, añade también una inclusión para ella en la página de índice del libro, en la posición alfabética correcta. Esa página es el punto de entrada de quien lee, y una sección que no esté incluida ahí resulta invisible en la práctica aunque se compile correctamente. ## Pasar todas las pruebas y la lista de comprobación antes de pedir revisión Comprueba todo lo siguiente antes de abrir o actualizar un cambio para su revisión, y otra vez después de cualquier reescritura. - La suite de pruebas completa pasa en local, usando el comando documentado de todas las pruebas y no una ejecución parcial. - Los commits están aplastados en uno solo y rebasados sobre la última rama main. - La descripción contiene una cláusula de cierre de incidencia correcta, o la cláusula se elimina por completo cuando no existe ninguna incidencia. Un número de incidencia equivocado es peor que ninguno. - Las listas que no se renderizan están ordenadas: enlaces, referencias, identificadores y entradas del manifiesto. El orden es lo que mantiene pequeños los diffs futuros. - Los enlaces de la documentación a páginas de referencia de API externas usan el segmento de versión comodín en lugar de una versión fija, para que el enlace no se pudra en la siguiente publicación. - El ejemplo usa el manejo de errores estándar del proyecto, sin atajos de pánico ante el fallo. - Los identificadores de código de la descripción se escriben como nombres entre comillas invertidas enlazados a sus páginas de referencia mediante definiciones de enlace al final del archivo. Después de enviarlo, vigila la ejecución de integración continua y corrige cualquier fallo que informe, en lugar de dejar un cambio en rojo abierto para que lo tenga que clasificar quien revisa.