Lorsqu'il est rendu, ce bloc apparaît comme un exemple de code standard. Pendant les tests, cependant, il est exécuté comme du code Python normal. Cette double nature garantit que la documentation reste propre pour les lecteurs tout en fournissant des exemples robustes et testables pour les développeurs. Cette approche est particulièrement impactante pour les domaines complexes comme l'IA, où les exemples impliquent souvent des étapes complexes de chargement de modèles et d'inférence.
## Intégration Transparente avec `pytest` et Fonctionnalités Avancées
Un différenciateur clé de l'approche de Hugging Face est son intégration transparente avec les frameworks de test modernes, en particulier `pytest`. Avec `hf-doc-builder` installé, `pytest` peut automatiquement découvrir et exécuter les blocs exécutables dans les fichiers Markdown, traitant chaque bloc comme un élément de test standard. Cela signifie que les exemples de documentation peuvent participer pleinement à l'infrastructure de test existante d'un projet, tirant parti des fonctionnalités puissantes de `pytest` comme les assertions, les fixtures, les outils de débogage et les rapports complets.
### L'Évolution de la Documentation Exécutable : `doctest` vs. `doc-builder`
| Fonctionnalité | `doctest` (Traditionnel) | `doc-builder` (Markdown exécutable moderne) |
| :--------------------------- | :-------------------------------------------------------- | :--------------------------------------------------- |
| **Approche de test** | Intègre les tests sous forme de sessions d'interpréteur dans la documentation | Traite les extraits de documentation comme du code Python normal pour les tests |
| **Intégration** | Module de la bibliothèque standard | Plugin `pytest` pour une intégration transparente |
| **Syntaxe de test** | `>>>` invites, correspondance de sortie attendue | Code Python standard, assertions `pytest` |
| **Flexibilité** | Limitée, correspondance de sortie fragile | Élevée, prend en charge les tests complexes, les décorateurs, le débogage |
| **Propreté de la documentation**| Peut encombrer la documentation avec des mécanismes de test | Préserve une documentation propre avec des directives masquées |
| **Débogage** | Comparaison de chaînes, inspection moins directe | Débogage Python standard, traces complètes |
| **Configuration/Démontage** | Peut ajouter du bruit aux exemples | Gère le contexte efficacement avec des blocs de continuation |
| **Source de vérité** | Format de la documentation et tests intégrés | Source Markdown, testée via l'exécution Python standard |
Le `doc-builder` introduit également les **blocs de continuation**, une fonctionnalité cruciale pour les tutoriels en plusieurs étapes. Ceux-ci permettent aux auteurs de diviser un exemple en plusieurs extraits visibles, comme `runnable:test_basic` suivi de `runnable:test_basic:2`. De manière cruciale, ces blocs partagent le même contexte d'exécution pendant les tests, permettant un flux pédagogique naturel sans forcer tout le code dans un seul long bloc. Cette flexibilité est vitale pour guider les utilisateurs à travers des utilisations complexes de modèles d'IA ou des pipelines de traitement de données.
Par exemple, un flux de travail de développement d'agent IA pourrait impliquer plusieurs étapes : la définition des outils de l'agent, l'initialisation de l'agent, puis l'exécution d'une requête. Les blocs de continuation permettent de présenter clairement chacune de ces étapes dans des sections de documentation distinctes tout en étant exécutées comme une séquence de test unique et cohérente, similaire à la façon dont les flux de travail agentiques avancés sont [Opérationnalisation de l'IA Agentique : Partie 1](/fr/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Maintenir une Documentation Propre tout en Assurant des Tests Robustes
L'une des solutions les plus élégantes du `doc-builder` est sa capacité à maintenir la documentation rendue propre, même lorsque la source Markdown contient des directives spécifiques aux tests. Les développeurs peuvent intégrer des commentaires comme `# doc-builder: hide` pour les lignes exécutables qui ne devraient pas apparaître dans la documentation, ou `# doc-builder: ignore-bare-assert` pour les assertions qui font partie du test mais dont le commentaire ne devrait pas être rendu. De même, les décorateurs `pytest` (`# pytest-decorator: ...`) sont supprimés lors du rendu.
Cela garantit que la documentation reste axée sur l'enseignement et la clarté, sans être encombrée par le boilerplate de test. L'utilisateur ne voit que le code pertinent, tandis que le système sous-jacent garantit sa fonctionnalité. Cet équilibre est essentiel pour la documentation des outils de développement, où l'attrait esthétique et la correction absolue sont primordiaux.
## Impact sur les Projets d'IA à Grande Échelle et au-Delà
Pour les dépôts massifs comme Transformers de Hugging Face, avec des centaines de pages de documentation et des milliers d'exemples, cette fonctionnalité est transformative. Elle automatise la prévention de la dérive de la documentation, un problème qui nécessiterait autrement un effort manuel immense ou entraînerait un flux constant d'exemples cassés. La documentation exécutable aide à maintenir la documentation et la base de code synchronisées, maintenant la fiabilité à une échelle où l'examen manuel est tout simplement infaisable. Cela s'aligne avec les efforts plus larges de la communauté de l'IA pour [Évaluer les Agents IA pour la Production](/fr/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) de manière rigoureuse et assurer la fiabilité.
En introduisant la documentation exécutable dans l'ère moderne de `pytest` et des pipelines CI/CD sophistiqués, Hugging Face démontre un engagement puissant envers l'expérience développeur et la qualité du code. L'objectif reste le même qu'il y a plus de deux décennies : les exemples de documentation devraient fonctionner. Mais maintenant, ils n'illustrent pas seulement comment le code *devrait* fonctionner, mais *prouvent* continuellement qu'il fonctionne, favorisant un écosystème plus fiable et digne de confiance pour le développement de l'IA.
Source originale
https://huggingface.co/blog/huggingface/runnable-examplesQuestions Fréquentes
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.
Restez informé
Recevez les dernières actualités IA dans votre boîte mail.