Cuando se renderiza, este bloque aparece como un ejemplo de código estándar. Durante las pruebas, sin embargo, se ejecuta como código Python normal. Esta doble naturaleza garantiza que la documentación permanezca limpia para los lectores al mismo tiempo que proporciona ejemplos robustos y probables para los desarrolladores. Este enfoque es particularmente impactante para dominios intrincados como la IA, donde los ejemplos a menudo implican pasos complejos de carga e inferencia de modelos.
## Integración Perfecta con `pytest` y Funcionalidades Avanzadas
Un diferenciador clave del enfoque de Hugging Face es su integración perfecta con los marcos de prueba modernos, particularmente `pytest`. Con `hf-doc-builder` instalado, `pytest` puede descubrir y ejecutar automáticamente bloques ejecutables dentro de los archivos Markdown, tratando cada bloque como un elemento de prueba estándar. Esto significa que los ejemplos de documentación pueden participar plenamente en la infraestructura de prueba existente de un proyecto, aprovechando las potentes características de `pytest` como aserciones, fixtures, herramientas de depuración e informes exhaustivos.
### La Evolución de la Documentación Ejecutable: `doctest` vs. `doc-builder`
| Característica | `doctest` (Tradicional) | `doc-builder` (Markdown Ejecutable Moderno) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Enfoque de Pruebas** | Incrusta pruebas como sesiones de intérprete en la documentación | Trata los fragmentos de documentación como código Python normal para pruebas |
| **Integración** | Módulo de biblioteca estándar | Plugin `pytest` para una integración perfecta |
| **Sintaxis de Prueba** | Indicadores `>>>`, coincidencia de salida esperada | Código Python estándar, aserciones `pytest` |
| **Flexibilidad** | Limitada, coincidencia de salida frágil | Alta, soporta pruebas complejas, decoradores, depuración |
| **Limpieza de la Documentación**| Puede llenar la documentación con la mecánica de prueba | Preserva una documentación limpia con directivas ocultas |
| **Depuración** | Comparación de cadenas, inspección menos directa | Depuración Python estándar, rastreos completos |
| **Configuración/Desmontaje** | Puede añadir ruido a los ejemplos | Gestiona el contexto eficazmente con bloques de continuación |
| **Fuente de Verdad** | Formato de documentación y pruebas incrustadas | Código fuente Markdown, probado mediante ejecución Python estándar |
El `doc-builder` también introduce los **bloques de continuación**, una característica crucial para tutoriales de varios pasos. Estos permiten a los autores dividir un ejemplo en múltiples fragmentos visibles, como `runnable:test_basic` seguido de `runnable:test_basic:2`. Fundamentalmente, estos bloques comparten el mismo contexto de ejecución durante las pruebas, lo que permite un flujo instruccional natural sin obligar todo el código en un bloque largo. Esta flexibilidad es vital para guiar a los usuarios a través del uso complejo de modelos de IA o pipelines de procesamiento de datos.
Por ejemplo, un flujo de trabajo de desarrollo de agentes de IA podría implicar varios pasos: definir las herramientas del agente, inicializar el agente y luego ejecutar una consulta. Los bloques de continuación permiten que cada uno de estos pasos se presente claramente en secciones separadas de la documentación, mientras se ejecutan como una única secuencia de prueba cohesiva, de forma similar a cómo se realizan los flujos de trabajo de agentes avanzados en [Operacionalización de la IA Agente: Parte 1](/es/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Manteniendo una Documentación Limpia y Garantizando Pruebas Robustas
Una de las soluciones más elegantes de `doc-builder` es su capacidad para mantener la documentación renderizada limpia, incluso cuando el Markdown fuente contiene directivas específicas para pruebas. Los desarrolladores pueden incrustar comentarios como `# doc-builder: hide` para líneas ejecutables que no deberían aparecer en la documentación, o `# doc-builder: ignore-bare-assert` para aserciones que forman parte de la prueba pero cuyo comentario no debería renderizarse. De manera similar, los decoradores de `pytest` (`# pytest-decorator: ...`) se eliminan durante la renderización.
Esto garantiza que la documentación permanezca centrada en la enseñanza y la claridad, sin estar abarrotada de código repetitivo de prueba. El usuario ve solo el código relevante, mientras que el sistema subyacente garantiza su funcionalidad. Este equilibrio es crítico para la documentación de herramientas para desarrolladores, donde tanto el atractivo estético como la corrección absoluta son primordiales.
## Impacto en Proyectos de IA a Gran Escala y Más Allá
Para repositorios masivos como Transformers de Hugging Face, con cientos de páginas de documentación y miles de ejemplos, esta característica es transformadora. Automatiza la prevención de la deriva de la documentación, un problema que de otro modo requeriría un inmenso esfuerzo manual o llevaría a un flujo constante de ejemplos rotos. La documentación ejecutable ayuda a mantener la documentación y la base de código sincronizadas, manteniendo la fiabilidad a una escala donde la revisión manual es simplemente inviable. Esto se alinea con esfuerzos más amplios en la comunidad de IA para [Evaluar Agentes de IA para Producción](/es/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) rigurosamente y asegurar la fiabilidad.
Al llevar la documentación ejecutable a la era moderna de `pytest` y los sofisticados pipelines de CI/CD, Hugging Face demuestra un poderoso compromiso con la experiencia del desarrollador y la calidad del código. El objetivo sigue siendo el mismo que hace más de dos décadas: los ejemplos de documentación deben funcionar. Pero ahora, no solo ilustran cómo *debería* funcionar el código, sino que continuamente *prueban* que lo hace, fomentando un ecosistema más fiable y digno de confianza para el desarrollo de la IA.
Fuente original
https://huggingface.co/blog/huggingface/runnable-examplesPreguntas Frecuentes
What is the core problem Hugging Face's runnable Markdown addresses?
Hugging Face's runnable Markdown addresses the pervasive problem of 'documentation drift,' where code examples in documentation become outdated and silently break as libraries and APIs evolve. This leads to user frustration and diminishes the credibility of the documentation. By making documentation examples runnable and testable, the doc-builder ensures that these snippets are continuously validated against the codebase, guaranteeing that they always work as advertised. This proactive approach prevents broken examples, enhances user trust, and improves the overall developer experience by providing reliable resources.
How does runnable Markdown differ from Python's traditional `doctest` module?
While both `doctest` and runnable Markdown aim for executable documentation, they differ significantly in their approach. `doctest` embeds tests directly into documentation syntax, requiring examples to mirror interactive interpreter sessions with expected output. This often leads to documentation being cluttered with test mechanics. Hugging Face's runnable Markdown, in contrast, treats documentation snippets as normal Python code living within Markdown files. It integrates seamlessly with modern testing frameworks like `pytest`, allowing for complex assertions, debugging, and standard test infrastructure. This separation of concerns ensures documentation remains clean and readable, while testing remains powerful and flexible, avoiding the limitations of `doctest`'s brittle output matching and verbose setup/teardown.
What are 'continuation blocks' in Hugging Face's `doc-builder`?
Continuation blocks are a powerful feature in Hugging Face's `doc-builder` that allow authors to split complex code examples or tutorials across multiple visible Markdown snippets while maintaining a shared execution context during testing. This means that a setup defined in one runnable block can be reused and built upon in a subsequent block, without forcing the documentation to present everything as one long, monolithic code fence. For example, `runnable:test_basic` can define initial variables, and `runnable:test_basic:2` can then use those variables. This enhances readability and instructional flow in documentation, making it easier to present multi-step processes without sacrificing the integrity of the underlying testable code.
How does `doc-builder` integrate with existing testing frameworks like `pytest`?
Hugging Face's `doc-builder` integrates natively with `pytest`, transforming runnable Markdown blocks into standard `pytest` test items. With `hf-doc-builder` installed, `pytest` automatically discovers and executes these blocks within Markdown files. This integration means that documentation examples can leverage the full power of `pytest`, including its assertion mechanisms, fixtures, decorators, and debugging tools. Failures appear as normal test failures with comprehensive tracebacks, allowing developers to debug effectively. This approach avoids the need for a special-purpose testing mini-language, embedding documentation tests directly into the project's existing, robust test infrastructure.
How does `doc-builder` ensure documentation remains clean despite embedded test logic?
A key design principle of `doc-builder` is to prevent test mechanics from polluting the user-facing documentation. Authors can embed test-only directives, such as `# pytest-decorator: transformers.testing_utils.slow` or `# doc-builder: hide` for lines that should be executable but not displayed, directly within the Markdown source. When the documentation is rendered, `doc-builder` intelligently strips these directives and comments, presenting a clean, readable code snippet to the user. This allows developers to write comprehensive tests alongside their examples without compromising the clarity and brevity expected of good documentation, maintaining a clear separation between the source code for testing and the rendered content for users.
What are the benefits of runnable documentation for large AI projects like Hugging Face Transformers?
For large AI projects such as Hugging Face Transformers, which involve extensive documentation and thousands of code examples, runnable documentation offers immense benefits. It drastically reduces 'documentation drift' by continuously validating examples against the evolving codebase, ensuring they remain accurate and functional. This prevents user frustration caused by broken examples and builds trust in the documentation's reliability. By integrating with `pytest`, it allows these projects to manage documentation tests within their existing CI/CD pipelines, making manual review of examples unnecessary at scale. This automated validation is crucial for maintaining the quality and usability of documentation in rapidly developing and complex software ecosystems.
Can runnable Markdown be adopted by other projects outside of Hugging Face?
Yes, the principles and mechanisms behind Hugging Face's runnable Markdown, particularly its integration with standard Python testing tools like `pytest` and its focus on separating testing logic from displayed documentation, are highly applicable and beneficial for any software project. While the `doc-builder` itself is specific to Hugging Face, the underlying ideas represent a best practice in developer tools. Other projects can implement similar systems using existing tools or adapt `doc-builder`'s concepts to ensure their documentation examples are continuously tested and reliable. This approach is a general solution to a common problem across the software development landscape, making documentation more robust and trustworthy.
Mantente Actualizado
Recibe las últimas noticias de IA en tu correo.