Виконуваний Markdown: Революція в тестуванні документації з Hugging Face

Документація слугує критично важливим містком між розробниками та їхніми інструментами, але її надійність часто підривається поширеною проблемою: дрейфом документації. У міру розвитку програмного забезпечення приклади коду в документації можуть непомітно ламатися, що призводить до розчарування, втрати часу та підриву довіри. Hugging Face, лідер в інноваціях ШІ, активно вирішує цю проблему за допомогою свого проєкту doc-builder, запроваджуючи виконувані Markdown-блоки, які гарантують, що приклади в документації є не просто ілюстративними, а ретельно протестованими. Цей сучасний підхід переосмислює наш підхід до виконуваної документації, поєднуючи чіткість якісних документів з надійністю безперервного тестування.

Виклик: Поєднання документації та цілісності коду

Основна філософія виконуваної документації не є новою. Десятиліттями спільнота Python виступала за приклади в документації, які користувачі могли б копіювати, вставляти та очікувати бездоганної роботи. Однак підтримка цього ідеалу у великих, швидко розвиваючихся проєктах, таких як бібліотека Transformers від Hugging Face, є монументальним завданням. Ручна перевірка непрактична, а традиційні методи часто змушують йти на компроміс між чіткою документацією та ефективним тестуванням.

Проблема виникає через фундаментальні відмінності у вимогах:

Приклади документації надають перевагу стислості, читабельності та орієнтованості на навчання. Вони мають бути вільними від "шуму".
Тести вимагають тверджень, налаштування/згортання, фікстур, моків та можливостей налагодження. Вони надають перевагу надійності та покриттю.

Коли ці дві турботи змушені існувати в одному форматі, одна з них часто страждає. doc-builder від Hugging Face має на меті вирішити цю напругу, дозволяючи документації залишатися бездоганною, тоді як її базові приклади ретельно перевіряються, забезпечуючи, що кожен фрагмент, з яким стикаються користувачі, є перевіреною істиною, а не просто прагненням. Це має вирішальне значення для підтримки довіри та прискорення впровадження розробниками у швидкоплинному світі ШІ.

Спадщина `doctest`: Ранні інновації та мінливі потреби

Концепція виконуваної документації вперше набула поширення в Python із запровадженням doctest у Python 2.1 (2001). Розроблений Тімом Пітерсом, doctest був елегантним рішенням: він аналізував приклади документації, відформатовані як сесії інтерактивного інтерпретатора Python (>>> add(2, 3)\n5), і перевіряв, чи відповідає вивід очікуванням. Ця інновація перетворила приклади документації на автоматичні регресійні тести, що стало значним кроком уперед для якості коду.

doctest особливо добре підходив для Python, мови, яка заохочувала інтерактивне дослідження. Для невеликих проєктів та простих API він працював винятково добре, надаючи простий, але потужний механізм для забезпечення функціональності базових прикладів. Він втілював дух «показуй, а не просто розповідай» у розробці програмного забезпечення, роблячи документацію активною частиною тестового набору.

Сучасне рішення Hugging Face: Виконувані Markdown-блоки

Усвідомлюючи обмеження старих підходів для великомасштабних, складних проєктів, проєкт doc-builder від Hugging Face представляє витончений погляд на виконувану документацію. Замість вбудовування тестів в синтаксис документації, він розглядає фрагменти документації як звичайний Python-код, що міститься в Markdown. Це ефективно перетворює Markdown на тонкий тестовий контейнер, відокремлюючи презентацію від методології тестування.

Виконуваний блок у Markdown виглядає так:

```py runnable:quickstart
from transformers import pipeline

pipe = pipeline("sentiment-analysis")
result = pipe("I love runnable docs!")

if not result:  # doc-builder: hide
    raise ValueError("pipeline returned no result")

print(result[0]["label"])
assert result[0]["score"] > 0.5  # doc-builder: ignore-bare-assert
```

При рендерингу цей блок відображається як стандартний приклад коду. Під час тестування, однак, він виконується як звичайний 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.

Підтримка чистої документації та забезпечення надійного тестування

Одне з найелегантніших рішень doc-builder — це його здатність підтримувати чистоту відрендереної документації, навіть якщо вихідний Markdown містить директиви, специфічні для тестування. Розробники можуть вбудовувати коментарі, такі як # doc-builder: hide для виконуваних рядків, які не повинні відображатися в документації, або # doc-builder: ignore-bare-assert для тверджень, що є частиною тесту, але чий коментар не повинен рендеритися. Аналогічно, декоратори pytest (# pytest-decorator: ...) видаляються під час рендерингу.

Це гарантує, що документація залишається зосередженою на навчанні та чіткості, не будучи захаращеною шаблонним кодом тестування. Користувач бачить лише відповідний код, тоді як базова система гарантує його функціональність. Цей баланс є критично важливим для документації інструментів розробника, де естетична привабливість і абсолютна коректність мають першочергове значення.

Вплив на великомасштабні проєкти ШІ та за їх межами

Для масштабних репозиторіїв, таких як Transformers від Hugging Face, з сотнями сторінок документації та тисячами прикладів, ця функція є трансформаційною. Вона кардинально зменшує «дрейф документації» шляхом безперервної перевірки прикладів на відповідність кодовій базі, що розвивається, забезпечуючи їх точність та функціональність. Це запобігає розчаруванню користувачів, викликаному непрацюючими прикладами, та підвищує довіру до надійності документації. Інтеграція з pytest дозволяє цим проєктам керувати тестами документації в їхніх існуючих CI/CD конвеєрах, роблячи ручний перегляд прикладів непотрібним у великому масштабі. Ця автоматизована перевірка є критично важливою для підтримки якості та зручності використання документації в швидко розвиваючихся та складних програмних екосистемах.

Це узгоджується з ширшими зусиллями в спільноті ШІ щодо ретельної Оцінки агентів ШІ для виробництва та забезпечення надійності.

Завдяки впровадженню виконуваної документації в сучасну еру 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.

Будьте в курсі

Отримуйте найсвіжіші новини ШІ на пошту.

Поділитися