Atvaizduojant, šis blokas atrodo kaip standartinis kodo pavyzdys. Tačiau testavimo metu jis vykdomas kaip įprastas Python kodas. Ši dvejopa prigimtis užtikrina, kad dokumentacija išlieka aiški skaitytojams, kartu teikdama patikimus, testuojamus pavyzdžius kūrėjams. Šis metodas ypač efektyvus sudėtingose srityse, tokiose kaip dirbtinis intelektas, kur pavyzdžiai dažnai apima sudėtingą modelio įkėlimą ir išvadų gavimo žingsnius.
## Sklandi integracija su `pytest` ir Išplėstinės funkcijos
Pagrindinis Hugging Face požiūrio išskirtinumas yra jo sklandi integracija su moderniomis testavimo sistemomis, ypač `pytest`. Įdiegus `hf-doc-builder`, `pytest` gali automatiškai atrasti ir vykdyti vykdomuosius blokus Markdown failuose, traktuodamas kiekvieną bloką kaip standartinį testavimo elementą. Tai reiškia, kad dokumentacijos pavyzdžiai gali visiškai dalyvauti esamoje projekto testavimo infrastruktūroje, naudojant galingas `pytest` funkcijas, tokias kaip patvirtinimai, fiksavimo mechanizmai, derinimo įrankiai ir išsamūs ataskaitų teikimas.
### Vykdomosios dokumentacijos evoliucija: `doctest` vs. `doc-builder`
| Funkcija | `doctest` (Tradicinis) | `doc-builder` (Modernus vykdomasis Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Testavimo Metodas** | Įterpia testus kaip interpretatoriaus sesijas į dokumentus | Traktuoja dokumentų fragmentus kaip įprastą Python kodą testavimui |
| **Integracija** | Standartinė bibliotekos modulis | `pytest` papildinys sklandžiai integracijai |
| **Testavimo Sintaksė** | `>>>` raginimai, numatomas išvesties suderinimas | Standartinis Python kodas, `pytest` patvirtinimai |
| **Lankstumas** | Ribotas, trapus išvesties suderinimas | Didelis, palaiko sudėtingus testus, dekoratorius, derinimą |
| **Dokumentacijos Švara** | Gali užteršti dokumentus testavimo mechanizmais | Išsaugo švarius dokumentus su paslėptomis direktyvomis |
| **Derinimas** | Eilučių palyginimas, mažiau tiesioginis tikrinimas | Standartinis Python derinimas, pilni atsekimo žurnalai |
| **Nustatymas/Išvalymas** | Gali pridėti triukšmo pavyzdžiams | Efektyviai valdo kontekstą su tęsinio blokais |
| **Tiesos Šaltinis** | Dokumentacijos formatas ir įterpti testai | Markdown šaltinis, patikrintas standartiniu Python vykdymu |
`doc-builder` taip pat pristato **tęsinio blokus** – esminę funkciją daugiapakopiems vadovėliams. Tai leidžia autoriams padalinti pavyzdį į kelis matomus fragmentus, pvz., `runnable:test_basic`, po kurio seka `runnable:test_basic:2`. Svarbiausia, kad šie blokai testų metu dalijasi tuo pačiu vykdymo kontekstu, leidžiant natūralų mokymo srautą, neversdami viso kodo į vieną ilgą bloką. Šis lankstumas yra gyvybiškai svarbus, norint vesti vartotojus per sudėtingą DI modelio naudojimą ar duomenų apdorojimo procesus.
Pavyzdžiui, DI agento kūrimo darbo eiga gali apimti kelis etapus: agento įrankių apibrėžimą, agento inicijavimą ir tada užklausos vykdymą. Tęsinio blokai leidžia kiekvieną iš šių etapų aiškiai pateikti atskiruose dokumentacijos skyriuose, kartu vykdant juos kaip vieną, nuoseklią testavimo seką, panašiai kaip pažangūs agentūriniai darbo srautai yra [Operacionalizuojant Agentūrinį DI: 1 Dalis](/lt/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Švarios Dokumentacijos palaikymas užtikrinant patikimą testavimą
Vienas iš elegantiškiausių „doc-builder“ sprendimų yra jo gebėjimas išlaikyti atvaizduotą dokumentaciją švarią, net jei šaltinio „Markdown“ faile yra testams skirtų direktyvų. Kūrėjai gali įterpti komentarus, tokius kaip „# doc-builder: hide“ vykdytinoms eilutėms, kurios neturėtų pasirodyti dokumentacijoje, arba „# doc-builder: ignore-bare-assert“ patvirtinimams, kurie yra testo dalis, bet kurių komentaras neturėtų būti atvaizduojamas. Panašiai „pytest“ dekoratoriai („# pytest-decorator: ...“) yra pašalinami atvaizdavimo metu.
Tai užtikrina, kad dokumentacija išliks orientuota į mokymą ir aiškumą, be testavimo šablonų užteršimo. Vartotojas mato tik atitinkamą kodą, o pagrindinė sistema garantuoja jo funkcionalumą. Ši pusiausvyra yra kritinė kūrėjo įrankių dokumentacijai, kurioje tiek estetinė išvaizda, tiek absoliutus teisingumas yra svarbiausi.
## Poveikis didelio masto dirbtinio intelekto projektams ir ne tik
Didžiuliams repozitorijams, tokiems kaip Hugging Face Transformers, turintiems šimtus dokumentacijos puslapių ir tūkstančius pavyzdžių, ši funkcija yra transformuojanti. Ji automatizuoja dokumentacijos neatitikimų prevenciją – problemą, kuri kitu atveju pareikalautų milžiniškų rankinių pastangų arba nuolatos sukeltų neveikiančius pavyzdžius. Vykdomoji dokumentacija padeda išlaikyti dokumentacijos ir kodų bazės sinchronizaciją, išlaikant patikimumą tokiu mastu, kai rankinis patikrinimas tiesiog neįmanomas. Tai dera su platesnėmis DI bendruomenės pastangomis griežtai [Vertinti DI agentus gamybai](/lt/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) ir užtikrinti patikimumą.
Atvedant vykdomąją dokumentaciją į modernią `pytest` ir sudėtingų CI/CD konvejerio erą, Hugging Face demonstruoja tvirtą įsipareigojimą kūrėjų patirčiai ir kodo kokybei. Tikslas išlieka tas pats, kaip ir prieš du dešimtmečius: dokumentacijos pavyzdžiai turi veikti. Bet dabar jie ne tik iliustruoja, kaip kodas *turėtų* veikti, bet ir nuolat *įrodo*, kad jis veikia, taip skatindami patikimesnę ir patikimesnę dirbtinio intelekto kūrimo ekosistemą.
Originalus šaltinis
https://huggingface.co/blog/huggingface/runnable-examplesDažniausiai užduodami klausimai
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.
Būkite informuoti
Gaukite naujausias AI naujienas el. paštu.