Când este redat, acest bloc apare ca un exemplu de cod standard. În timpul testării, însă, este executat ca un cod Python normal. Această natură duală asigură că documentația rămâne curată pentru cititori, oferind în același timp exemple robuste, testabile, pentru dezvoltatori. Această abordare este deosebit de impactantă pentru domenii complexe precum AI, unde exemplele implică adesea încărcarea complexă a modelelor și pași de inferență.
## Integrare Perfectă cu `pytest` și Funcționalități Avansate
Un diferențiator cheie al abordării Hugging Face este integrarea sa perfectă cu framework-urile de testare moderne, în special `pytest`. Cu `hf-doc-builder` instalat, `pytest` poate descoperi și executa automat blocuri executabile în fișierele Markdown, tratând fiecare bloc ca un element de test standard. Aceasta înseamnă că exemplele de documentație pot participa pe deplin la infrastructura de testare existentă a unui proiect, utilizând funcționalitățile puternice ale `pytest`, cum ar fi aserțiunile, fixturele, instrumentele de depanare și raportarea completă.
### Evoluția Documentației Executabile: `doctest` vs. `doc-builder`
| Caracteristică | `doctest` (Tradițional) | `doc-builder` (Markdown Executabil Modern) |
| :------------------------------ | :----------------------------------------------------- | :------------------------------------------------------- |
| **Abordare de Testare** | Încorporează teste ca sesiuni de interpretor în documente | Tratează fragmentele de documente ca cod Python normal pentru testare |
| **Integrare** | Modul din biblioteca standard | Plugin `pytest` pentru integrare perfectă |
| **Sintaxă Test** | `>>>` prompt-uri, potrivire cu ieșirea așteptată | Cod Python standard, aserțiuni `pytest` |
| **Flexibilitate** | Limitată, potrivire fragilă a ieșirilor | Ridicată, suportă teste complexe, decoratori, depanare |
| **Curățenia Documentației** | Poate aglomera documentele cu mecanisme de testare | Păstrează documentele curate cu directive ascunse |
| **Depanare** | Comparare șiruri, inspecție mai puțin directă | Depanare Python standard, tracebacks complete |
| **Configurare/Dezafectare** | Poate adăuga "zgomot" exemplelor | Gestionează contextul eficient cu blocuri de continuare |
| **Sursa de Adevăr** | Formatul documentației și testele încorporate | Sursa Markdown, testată prin execuție Python standard |
`doc-builder` introduce, de asemenea, **blocuri de continuare**, o funcționalitate crucială pentru tutorialele în mai multe etape. Acestea permit autorilor să împartă un exemplu în mai multe fragmente vizibile, cum ar fi `runnable:test_basic` urmat de `runnable:test_basic:2`. Crucial este că aceste blocuri partajează același context de execuție în timpul testelor, permițând un flux instrucțional natural fără a forța tot codul într-un singur bloc lung. Această flexibilitate este vitală pentru a ghida utilizatorii prin utilizarea complexă a modelelor AI sau a fluxurilor de lucru de prelucrare a datelor.
De exemplu, un flux de lucru de dezvoltare a agenților AI ar putea implica mai mulți pași: definirea instrumentelor agentului, inițializarea agentului și apoi rularea unei interogări. Blocurile de continuare permit ca fiecare dintre acești pași să fie prezentați clar în secțiuni separate ale documentației, în timp ce sunt executați ca o singură secvență de testare coezivă, similar cu modul în care fluxurile de lucru agențiale avansate sunt [Operationalizarea AI agentiale: Partea 1](/ro/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Menținerea Documentației Curate Asigurând în Același Timp o Testare Robustă
Una dintre cele mai elegante soluții ale `doc-builder`-ului este capacitatea sa de a menține documentația redată curată, chiar și atunci când sursa Markdown conține directive specifice testării. Dezvoltatorii pot încorpora comentarii precum `# doc-builder: hide` pentru linii executabile care nu ar trebui să apară în documentație, sau `# doc-builder: ignore-bare-assert` pentru aserțiuni care fac parte din test, dar al căror comentariu nu ar trebui să fie redat. În mod similar, decoratorii `pytest` (`# pytest-decorator: ...`) sunt eliminați în timpul redării.
Acest lucru asigură că documentația rămâne concentrată pe predare și claritate, fără a fi aglomerată de cod standard repetitiv (boilerplate) de testare. Utilizatorul vede doar codul relevant, în timp ce sistemul subiacent garantează funcționalitatea acestuia. Acest echilibru este critic pentru documentația instrumentelor pentru dezvoltatori, unde atât atractivitatea estetică, cât și corectitudinea absolută sunt primordiale.
## Impactul Asupra Proiectelor AI la Scară Mare și Nu Numai
Pentru depozite masive precum Transformers de la Hugging Face, cu sute de pagini de documentație și mii de exemple, această funcționalitate este transformatoare. Automatizează prevenirea inconsistentei documentației, o problemă care altfel ar necesita un efort manual imens sau ar duce la un flux constant de exemple defecte. Documentația executabilă ajută la menținerea sincronizării documentației cu baza de cod, menținând fiabilitatea la o scară unde revizuirea manuală este pur și simplu imposibilă. Acest lucru se aliniază cu eforturile mai ample din comunitatea AI de a [Evalua Agenții AI pentru Producție](/ro/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) riguros și de a asigura fiabilitatea.
Prin aducerea documentației executabile în era modernă a `pytest` și a fluxurilor CI/CD sofisticate, Hugging Face demonstrează un angajament puternic față de experiența dezvoltatorului și calitatea codului. Scopul rămâne același ca acum peste două decenii: exemplele din documentație ar trebui să funcționeze. Dar acum, ele nu numai că ilustrează cum *ar trebui* să funcționeze codul, ci *dovedesc* continuu că funcționează, promovând un ecosistem mai fiabil și mai demn de încredere pentru dezvoltarea AI.
Sursa originală
https://huggingface.co/blog/huggingface/runnable-examplesÎntrebări frecvente
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.
Rămâi la curent
Primește ultimele știri AI în inbox-ul tău.