Wanneer dit blok wordt gerenderd, verschijnt het als een standaard codevoorbeeld. Tijdens het testen wordt het echter uitgevoerd als normale Python-code. Deze tweeledige aard zorgt ervoor dat de documentatie schoon blijft voor lezers, terwijl robuuste, testbare voorbeelden worden geboden voor ontwikkelaars. Deze aanpak is bijzonder impactvol voor complexe domeinen zoals AI, waar voorbeelden vaak complexe modellading en inferentiestappen omvatten.
## Naadloze Integratie met `pytest` en Geavanceerde Functies
Een belangrijk onderscheidend kenmerk van Hugging Face's aanpak is de naadloze integratie met moderne testframeworks, met name `pytest`. Met `hf-doc-builder` geïnstalleerd, kan `pytest` automatisch uitvoerbare blokken binnen Markdown-bestanden ontdekken en uitvoeren, waarbij elk blok als een standaard testitem wordt behandeld. Dit betekent dat documentatievoorbeelden volledig kunnen deelnemen aan de bestaande testinfrastructuur van een project, waarbij gebruik wordt gemaakt van de krachtige functies van `pytest`, zoals beweringen (assertions), fixtures, debugging-tools en uitgebreide rapportage.
### De Evolutie van Uitvoerbare Documentatie: `doctest` versus `doc-builder`
| Kenmerk | `doctest` (Traditioneel) | `doc-builder` (Moderne Uitvoerbare Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Testbenadering** | Sluit tests in als interpretersessies in docs | Behandelt docs-fragmenten als normale Python-code voor testen |
| **Integratie** | Standaard bibliotheekmodule | `pytest`-plugin voor naadloze integratie |
| **Testsyntaxis** | `>>>` prompts, verwachte uitvoer-matching | Standaard Python-code, `pytest`-beweringen |
| **Flexibiliteit** | Beperkt, fragiele uitvoer-matching | Hoog, ondersteunt complexe tests, decorators, debugging |
| **Documentatie Netheid** | Kan docs rommelig maken met testmechanismen | Behoudt schone docs met verborgen richtlijnen |
| **Foutopsporing** | Stringvergelijking, minder directe inspectie | Standaard Python-foutopsporing, volledige tracebacks |
| **Setup/Teardown** | Kan ruis toevoegen aan voorbeelden | Beheert context effectief met vervolgblokken |
| **Bron van Waarheid** | Documentatieformaat en ingebedde tests | Markdown-bron, getest via standaard Python-uitvoering |
De `doc-builder` introduceert ook **vervolgblokken**, een cruciale functie voor tutorials met meerdere stappen. Deze stellen auteurs in staat om een voorbeeld te splitsen over meerdere zichtbare fragmenten, zoals `runnable:test_basic` gevolgd door `runnable:test_basic:2`. Cruciaal is dat deze blokken dezelfde uitvoeringscontext delen tijdens tests, waardoor een natuurlijke instructiestroom mogelijk is zonder alle code in één lang blok te forceren. Deze flexibiliteit is essentieel voor het begeleiden van gebruikers door complex AI-modelgebruik of dataprocessing-pijplijnen.
Een AI-agent ontwikkelworkflow kan bijvoorbeeld verschillende stappen omvatten: het definiëren van de tools van de agent, het initialiseren van de agent, en vervolgens het uitvoeren van een query. Vervolgblokken maken het mogelijk dat elk van deze stappen duidelijk wordt gepresenteerd in afzonderlijke documentatiesecties, terwijl ze worden uitgevoerd als één enkele, coherente testreeks, vergelijkbaar met hoe geavanceerde agentic workflows zijn [Operationele AI-Agenten: Deel 1](/nl/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Schone Documentatie Behouden en Tegelijk Robuuste Tests Garanderen
Een van `doc-builder`'s meest elegante oplossingen is het vermogen om de gerenderde documentatie schoon te houden, zelfs wanneer de bron-Markdown testspecifieke richtlijnen bevat. Ontwikkelaars kunnen commentaren zoals '# doc-builder: hide' insluiten voor uitvoerbare regels die niet in de documentatie mogen verschijnen, of '# doc-builder: ignore-bare-assert' voor beweringen die deel uitmaken van de test, maar waarvan het commentaar niet moet worden gerenderd. Op dezelfde manier worden `pytest`-decorators (`# pytest-decorator: ...`) verwijderd tijdens het renderen.
Dit zorgt ervoor dat de documentatie gericht blijft op onderwijs en duidelijkheid, zonder te worden overladen met testboilerplate. De gebruiker ziet alleen de relevante code, terwijl het onderliggende systeem de functionaliteit ervan garandeert. Dit evenwicht is cruciaal voor documentatie van ontwikkelaarstools, waar zowel esthetische aantrekkingskracht als absolute correctheid van het grootste belang zijn.
## Impact op grootschalige AI-projecten en verder
Voor enorme repositories zoals Hugging Face's Transformers, met honderden documentatiepagina's en duizenden voorbeelden, is deze functie transformatief. Het automatiseert het voorkomen van documentatiedrift, een probleem dat anders immense handmatige inspanning zou vereisen of zou leiden tot een constante stroom van kapotte voorbeelden. Uitvoerbare documentatie helpt de documentatie en codebase synchroon te houden, waardoor de betrouwbaarheid wordt gewaarborgd op een schaal waar handmatige controle simpelweg onhaalbaar is. Dit sluit aan bij bredere inspanningen in de AI-gemeenschap om rigoureus [AI-agenten Evalueren voor Productie](/nl/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) te testen en betrouwbaarheid te garanderen.
Door uitvoerbare documentatie naar het moderne tijdperk van `pytest` en geavanceerde CI/CD-pijplijnen te brengen, toont Hugging Face een krachtige toewijding aan ontwikkelaarservaring en codekwaliteit. Het doel blijft hetzelfde als ruim twee decennia geleden: documentatievoorbeelden moeten werken. Maar nu illustreren ze niet alleen hoe code *zou moeten* werken, maar *bewijzen* ze ook continu dat het werkt, wat een betrouwbaarder en geloofwaardiger ecosysteem voor AI-ontwikkeling bevordert.
Veelgestelde vragen
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.
Blijf op de hoogte
Ontvang het laatste AI-nieuws in je inbox.