Quan es renderitza, aquest bloc apareix com un exemple de codi estàndard. Durant les proves, però, s'executa com a codi Python normal. Aquesta doble naturalesa garanteix que la documentació romangui neta per als lectors, alhora que proporciona exemples robustos i provables per als desenvolupadors. Aquest enfocament és particularment impactant per a dominis intricats com la IA, on els exemples sovint impliquen la càrrega de models complexos i passos d'inferència.
## Integració Sense Problemes amb `pytest` i Funcions Avançades
Un diferenciador clau de l'enfocament de Hugging Face és la seva integració perfecta amb els marcs de prova moderns, especialment `pytest`. Amb `hf-doc-builder` instal·lat, `pytest` pot descobrir i executar automàticament blocs executables dins dels fitxers Markdown, tractant cada bloc com un element de prova estàndard. Això significa que els exemples de documentació poden participar plenament en la infraestructura de proves existent d'un projecte, aprofitant les potents característiques de `pytest` com les afirmacions, les *fixtures*, les eines de depuració i els informes complets.
### L'Evolució de la Documentació Executable: `doctest` vs. `doc-builder`
| Característica | `doctest` (Tradicional) | `doc-builder` (Markdown Executable Modern) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Enfocament de les Proves** | Incrusta proves com a sessions d'intèrpret en la documentació | Tracta els fragments de documentació com a codi Python normal per a les proves |
| **Integració** | Mòdul de la llibreria estàndard | Plugin de `pytest` per a una integració perfecta |
| **Sintaxi de les Proves** | Indicadors `>>>`, concordança de sortida esperada | Codi Python estàndard, afirmacions de `pytest` |
| **Flexibilitat** | Limitada, concordança de sortida fràgil | Alta, suporta proves complexes, decoradors, depuració |
| **Neteja de la Documentació**| Pot omplir la documentació amb mecanismes de prova | Preserva la documentació neta amb directives ocultes |
| **Depuració** | Comparació de cadenes, inspecció menys directa | Depuració estàndard de Python, traces de pila completes |
| **Configuració/Desmuntatge** | Pot afegir soroll als exemples | Gestiona el context eficaçment amb blocs de continuació |
| **Font de la Veritat** | Format de documentació i proves incrustades | Font Markdown, provada mitjançant l'execució estàndard de Python |
El `doc-builder` també introdueix els **blocs de continuació**, una característica crucial per a tutorials de diversos passos. Aquests permeten als autors dividir un exemple en múltiples fragments visibles, com ara `runnable:test_basic` seguit de `runnable:test_basic:2`. Crucialment, aquests blocs comparteixen el mateix context d'execució durant les proves, permetent un flux instructiu natural sense obligar tot el codi a un bloc llarg. Aquesta flexibilitat és vital per guiar els usuaris a través de l'ús complex de models d'IA o de pipelines de processament de dades.
Per exemple, un flux de treball de desenvolupament d'agents d'IA podria implicar diversos passos: definir les eines de l'agent, inicialitzar l'agent i després executar una consulta. Els blocs de continuació permeten que cadascun d'aquests passos es presenti clarament en seccions de documentació separades mentre s'executen com una seqüència de prova única i cohesiva, de manera similar a com es tracten els fluxos de treball agentics avançats a [Operativització d'IA agentica: Part 1](/ca/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Mantenint una Documentació Neta Garantint Proves Robustes
Una de les solucions més elegants del `doc-builder` és la seva capacitat per mantenir la documentació renderitzada neta, fins i tot quan la font Markdown conté directives específiques per a proves. Els desenvolupadors poden incrustar comentaris com `# doc-builder: hide` per a línies executables que no haurien d'aparèixer en la documentació, o `# doc-builder: ignore-bare-assert` per a afirmacions que formen part de la prova però el comentari de les quals no hauria de ser renderitzat. De manera similar, els decoradors de `pytest` (`# pytest-decorator: ...`) s'eliminen durant la renderització.
Això garanteix que la documentació es mantingui centrada en l'ensenyament i la claredat, sense ser atapeïda per codi repetitiu de proves. L'usuari veu només el codi rellevant, mentre que el sistema subjacent garanteix la seva funcionalitat. Aquest equilibri és crític per a la documentació d'eines per a desenvolupadors, on tant l'atractiu estètic com la correcció absoluta són primordials.
## Impacte en Projectes d'IA a Gran Escala i Més Enllà
Per a repositoris massius com els Transformers de Hugging Face, amb centenars de pàgines de documentació i milers d'exemples, aquesta característica és transformadora. Automatitza la prevenció de la deriva de la documentació, un problema que d'altra altra manera requeriria un esforç manual immens o portaria a un flux constant d'exemples trencats. La documentació executable ajuda a mantenir la documentació i la base de codi sincronitzades, mantenint la fiabilitat a una escala on la revisió manual és simplement inviable. Això s'alinea amb esforços més amplis en la comunitat d'IA per a [Avaluar Agents d'IA per a la Producció](/ca/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) rigorosament i garantir la fiabilitat.
En portar la documentació executable a l'era moderna de `pytest` i dels sofisticats pipelines de CI/CD, Hugging Face demostra un poderós compromís amb l'experiència del desenvolupador i la qualitat del codi. L'objectiu segueix sent el mateix que fa més de dues dècades: els exemples de documentació han de funcionar. Però ara, no només il·lustren com el codi *hauria* de funcionar, sinó que contínuament *demostren* que ho fa, fomentant un ecosistema més fiable i digne de confiança per al desenvolupament d'IA.
Preguntes freqüents
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.
Manteniu-vos al dia
Rebeu les últimes notícies d'IA al correu.