Кога е рендериран, овој блок се појавува како стандарден пример на код. За време на тестирањето, сепак, тој се извршува како нормален Python код. Оваа двојна природа гарантира дека документацијата останува чиста за читателите, истовремено обезбедувајќи робусни, тестирачки примери за програмерите. Овој пристап е особено влијателен за сложени домени како вештачката интелигенција, каде што примерите често вклучуваат комплексни чекори за вчитување модели и заклучување.
## Беспрекорна интеграција со `pytest` и напредни функции
Клучна диференцијација на пристапот на Hugging Face е неговата беспрекорна интеграција со модерните рамки за тестирање, особено `pytest`. Со инсталиран `hf-doc-builder`, `pytest` може автоматски да открива и извршува извршливи блокови во Markdown датотеки, третирајќи го секој блок како стандардна тест ставка. Ова значи дека примерите од документацијата можат целосно да учествуваат во постоечката тест инфраструктура на проектот, искористувајќи ги моќните карактеристики на `pytest` како тврдења, фикстури, алатки за дебагирање и сеопфатно известување.
### Еволуцијата на извршната документација: `doctest` наспроти `doc-builder`
| Карактеристика | `doctest` (Традиционален) | `doc-builder` (Модерен Извршлив Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Пристап на тестирање** | Вметнува тестови како сесии на интерпретерот во документацијата | Ги третира снипетите од документацијата како нормален Python код за тестирање |
| **Интеграција** | Модул од стандардна библиотека | `pytest` приклучок за беспрекорна интеграција |
| **Синтакса на тест** | `>>>` наредби, совпаѓање на очекуван излез | Стандарден Python код, `pytest` тврдења |
| **Флексибилност** | Ограничена, кршливо совпаѓање на излез | Висока, поддржува комплексни тестови, декоратори, дебагирање |
| **Чистота на документацијата**| Може да ја натрупува документацијата со механика на тестирање | Ја зачувува чистата документација со скриени директиви |
| **Дебагирање** | Споредба на стрингови, помалку директна инспекција | Стандардно Python дебагирање, целосни траги |
| **Поставување/Отстранување** | Може да додаде шум на примерите | Ефективно управува со контекстот со блокови за продолжување |
| **Извор на вистина** | Формат на документација и вградени тестови | Извор на Markdown, тестиран преку стандардно извршување на Python |
`doc-builder` исто така воведува **блокови за продолжување**, клучна карактеристика за туторијали во повеќе чекори. Тие им овозможуваат на авторите да поделат пример низ повеќе видливи снипети, како `runnable:test_basic` проследено со `runnable:test_basic:2`. Клучно, овие блокови го делат истиот контекст на извршување за време на тестовите, овозможувајќи природен тек на наставата без да се принудува целиот код во еден долг блок. Оваа флексибилност е витална за водење на корисниците низ сложено користење на модели за вештачка интелигенција или податочни процесни цевководи.
На пример, работниот тек за развој на агент за вештачка интелигенција може да вклучува неколку чекори: дефинирање на алатките на агентот, иницијализирање на агентот, а потоа извршување на барање. Блоковите за продолжување овозможуваат секој од овие чекори да биде јасно претставен во посебни делови од документацијата додека се извршуваат како една, кохезивна тест секвенца, слично како што напредните агентски работни текови се [Операционализирање на агентската вештачка интелигенција: Дел 1](/mk/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Одржување чиста документација додека се обезбедува робусно тестирање
Едно од најелегантните решенија на `doc-builder` е неговата способност да ја одржува рендерираната документација чиста, дури и кога изворниот Markdown содржи директиви специфични за тестирање. Програмерите можат да вметнат коментари како `# doc-builder: hide` за извршни линии кои не треба да се појавуваат во документацијата, или `# doc-builder: ignore-bare-assert` за тврдења кои се дел од тестот, но чиј коментар не треба да биде рендериран. Слично на тоа, `pytest` декораторите (`# pytest-decorator: ...`) се отстрануваат за време на рендерирањето.
Ова гарантира дека документацијата останува фокусирана на подучување и јасност, без да биде натрупана од тестирачки шаблонски код. Корисникот го гледа само релевантниот код, додека основниот систем ја гарантира неговата функционалност. Овој баланс е критичен за документацијата за алатките за програмери, каде што и естетскиот изглед и апсолутната исправност се најважни.
## Влијание врз големи проекти за вештачка интелигенција и пошироко
За масивни репозитории како Transformers на Hugging Face, со стотици страници документација и илјадници примери, оваа карактеристика е трансформативна. Таа ја автоматизира превенцијата од документациски дрифт, проблем кој инаку би барал огромен рачен напор или би довел до постојан прилив на нефункционални примери. Извршливата документација помага да се задржи документацијата и кодната база синхронизирани, одржувајќи ја доверливоста во обем каде што рачната проверка е едноставно неизводлива. Ова се усогласува со пошироките напори во заедницата за вештачка интелигенција за ригорозно [Евалуација на агенти за вештачка интелигенција за продукција](/mk/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) и обезбедување на сигурност.
Со воведувањето на извршната документација во модерната ера на `pytest` и софистицираните CI/CD процеси, Hugging Face покажува моќна посветеност на искуството на програмерите и квалитетот на кодот. Целта останува иста како што беше пред повеќе од две децении: примерите од документацијата треба да работат. Но сега, тие не само што илустрираат како кодот *треба* да работи, туку континуирано *докажуваат* дека работи, поттикнувајќи посигурен и доверлив екосистем за развој на вештачка интелигенција.
Оригинален извор
https://huggingface.co/blog/huggingface/runnable-examplesЧесто поставувани прашања
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.
Бидете информирани
Добивајте ги најновите AI вести на е-пошта.