При рендериране този блок се появява като стандартен кодов пример. По време на тестване обаче той се изпълнява като нормален 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` въвежда и **блокове за продължение** (continuation blocks), ключова функция за уроци с няколко стъпки. Те позволяват на авторите да разделят пример между множество видими фрагменти, като `runnable:test_basic`, последвано от `runnable:test_basic:2`. От решаващо значение е, че тези блокове споделят един и същ контекст на изпълнение по време на тестове, което позволява естествен поток на обучение, без да се налага целият код да бъде в един дълъг блок. Тази гъвкавост е жизненоважна за насочване на потребителите през сложно използване на AI модели или пайплайни за обработка на данни.
Например, работният процес за разработка на AI агент може да включва няколко стъпки: дефиниране на инструментите на агента, инициализиране на агента и след това изпълнение на заявка. Блоковете за продължение позволяват всяка от тези стъпки да бъде представена ясно в отделни секции на документацията, като същевременно се изпълняват като една единна, кохезивна тестова последователност, подобно на това как усъвършенстваните агентни работни процеси са [Операционализиране на агентен ИИ: Част 1](/bg/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Поддържане на чиста документация, като същевременно се осигурява надеждно тестване
Едно от най-елегантните решения на `doc-builder` е способността му да поддържа рендираната документация чиста, дори когато изходният Markdown съдържа директиви, специфични за тестовете. Разработчиците могат да вграждат коментари като `# doc-builder: hide` за изпълними редове, които не трябва да се показват в документацията, или `# doc-builder: ignore-bare-assert` за твърдения, които са част от теста, но чийто коментар не трябва да се рендира. По същия начин `pytest` декораторите (`# pytest-decorator: ...`) се премахват по време на рендиране.
Това гарантира, че документацията остава фокусирана върху обучението и яснотата, без да бъде затрупвана от тестови шаблони. Потребителят вижда само съответния код, докато основната система гарантира неговата функционалност. Този баланс е от решаващо значение за документацията на инструментите за разработчици, където както естетическата привлекателност, така и абсолютната коректност са от първостепенно значение.
## Въздействие върху широкомащабни AI проекти и отвъд тях
За масивни хранилища като Transformers на Hugging Face, със стотици страници документация и хиляди примери, тази функция е трансформираща. Тя автоматизира предотвратяването на разминаването на документацията, проблем, който иначе би изисквал огромни ръчни усилия или би довел до постоянен поток от счупени примери. Изпълнимата документация помага да се поддържат документацията и кодовата база в синхрон, поддържайки надеждност в мащаб, където ръчният преглед е просто неосъществим. Това е в съответствие с по-широките усилия в AI общността за стриктно [Оценяване на AI агенти за производство](/bg/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 новини по имейл.