Runnable Markdown: Pagbabago sa Pagsubok ng Dokumentasyon gamit ang Hugging Face

Ang dokumentasyon ay nagsisilbing mahalagang tulay sa pagitan ng mga developer at kanilang mga tool, ngunit ang pagiging maaasahan nito ay madalas na nasisira ng isang laganap na problema: paglihis ng dokumentasyon (documentation drift). Habang umuunlad ang software, ang mga halimbawa ng code sa dokumentasyon ay maaaring tahimik na masira, na nagdudulot ng pagkadismaya, pag-aksaya ng oras, at pagguho ng tiwala. Tinutugunan ng Hugging Face, isang lider sa inobasyon ng AI, ang hamong ito sa pamamagitan ng kanilang proyektong doc-builder, na nagpapakilala ng mga runnable Markdown block na tinitiyak na ang mga halimbawa ng dokumentasyon ay hindi lamang naglalarawan, kundi mahigpit ding sinusuri. Ang modernong pamamaraang ito ay nagbibigay-kahulugan muli sa kung paano natin nilalapitan ang naisasagawang dokumentasyon, na pinagsasama ang kalinawan ng mahusay na dokumento sa katatagan ng tuloy-tuloy na pagsubok.

Ang Hamon: Pagdugtong sa Dokumentasyon at Integridad ng Code

Ang pangunahing pilosopiya sa likod ng runnable na dokumentasyon ay hindi bago. Sa loob ng mga dekada, isinusulong ng komunidad ng Python ang mga halimbawa sa dokumentasyon na maaaring kopyahin, i-paste, at inaasahang gumana nang walang aberya ng mga user. Gayunpaman, ang pagpapanatili ng ideal na ito sa malalaki at mabilis na nagbabagong proyekto tulad ng library ng Transformers ng Hugging Face ay isang napakalaking gawain. Hindi praktikal ang manu-manong pagpapatunay, at ang tradisyonal na pamamaraan ay madalas na nagpipilit ng kompromiso sa pagitan ng malinaw na dokumentasyon at epektibong pagsubok.

Ang problema ay nagmumula sa mga pangunahing pagkakaiba sa mga kinakailangan:

Ang mga halimbawa ng dokumentasyon ay inuuna ang pagiging maikli, nababasa, at ang pagtutok sa pagtuturo. Ang layunin nila ay maging malaya sa "ingay."
Ang mga pagsubok ay nangangailangan ng assertions, setup/teardown, fixtures, mocking, at mga kakayahan sa debugging. Inuuna nila ang katatagan at saklaw.

Kapag ang dalawang isyung ito ay pinilit sa iisang format, madalas na nagdurusa ang isa. Layunin ng doc-builder ng Hugging Face na lutasin ang tensyon na ito sa pamamagitan ng pagpapahintulot sa dokumentasyon na manatiling malinis habang ang pinagbabatayang halimbawa nito ay mahigpit na nabe-validate, tinitiyak na ang bawat snippet na makikita ng user ay isang mapapatunayang katotohanan, hindi lamang isang hangarin. Mahalaga ito para sa pagpapanatili ng kredibilidad at pagpapabilis ng pagtanggap ng developer sa mabilis na mundo ng AI.

Ang Pamana ng `doctest`: Maagang Inobasyon at Nagbabagong Pangangailangan

Ang konsepto ng naisasagawang dokumentasyon ay nakakuha ng maagang atensyon sa Python sa pagpapakilala ng doctest sa Python 2.1 (2001). Ginawa ni Tim Peters, ang doctest ay isang eleganteng solusyon: pinaproseso nito ang mga halimbawa ng dokumentasyon na naka-format tulad ng mga interactive na sesyon ng interpreter ng Python (>>> add(2, 3)\n5) at nabe-verify na ang output ay tumutugma sa mga inaasahan. Ang inobasyong ito ay ginawang awtomatikong regression test ang mga halimbawa ng dokumentasyon, isang malaking pagsulong para sa kalidad ng code.

Ang doctest ay partikular na angkop para sa Python, isang wika na naghihikayat ng interactive na paggalugad. Para sa maliliit na proyekto at simpleng API, gumana ito nang pambihira, na nagbibigay ng isang simple ngunit makapangyarihang mekanismo upang matiyak na nananatiling gumagana ang mga pangunahing halimbawa. Isinabuhay nito ang diwa ng "ipakita, huwag lang sabihin" sa pagbuo ng software, na ginagawang aktibong bahagi ng testing suite ang dokumentasyon.

Modernong Solusyon ng Hugging Face: Mga Runnable Markdown Block

Sa pagkilala sa mga limitasyon ng mas lumang pamamaraan para sa malalaki at kumplikadong proyekto, ipinapakilala ng proyektong doc-builder ng Hugging Face ang isang sopistikadong paraan sa runnable documentation. Sa halip na isama ang mga pagsubok sa loob ng syntax ng dokumentasyon, tinuturing nito ang mga snippet ng dokumentasyon bilang ordinaryong Python code na nasa loob ng Markdown. Ito ay epektibong ginagawang isang manipis na lalagyan ng pagsubok ang Markdown, na naghihiwalay sa presentasyon mula sa metodolohiya ng pagsubok.

Ganito ang hitsura ng isang runnable block sa 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
```

Kapag na-render, lumalabas ang block na ito bilang isang standard na halimbawa ng code. Gayunpaman, sa panahon ng pagsubok, ito ay isinasagawa bilang normal na Python code. Tinitiyak ng dual na kalikasan na ito na nananatiling malinis ang dokumentasyon para sa mga mambabasa habang nagbibigay ng matibay, testable na halimbawa para sa mga developer. Ang pamamaraang ito ay partikular na maimpluwensya para sa kumplikadong domain tulad ng AI, kung saan ang mga halimbawa ay madalas na kinabibilangan ng kumplikadong model loading at inference steps.

Walang Putol na Integrasyon sa `pytest` at Advanced na Mga Tampok

Ang isang pangunahing pagkakaiba ng pamamaraan ng Hugging Face ay ang walang putol na integrasyon nito sa mga modernong testing framework, partikular ang pytest. Kapag naka-install ang hf-doc-builder, awtomatikong nadidiskubre at isinasagawa ng pytest ang mga runnable block sa loob ng mga Markdown file, na tinuturing ang bawat block bilang isang standard test item. Nangangahulugan ito na ang mga halimbawa ng dokumentasyon ay maaaring ganap na makilahok sa umiiral na imprastraktura ng pagsubok ng isang proyekto, na gumagamit ng makapangyarihang mga feature ng pytest tulad ng assertions, fixtures, debugging tools, at komprehensibong pag-uulat.

Ang Ebolusyon ng Naisasagawang Dokumentasyon: `doctest` vs. `doc-builder`

Tampok	`doctest` (Tradisyonal)	`doc-builder` (Modernong Runnable Markdown)
Pamamaraan ng Pagsubok	Nag-e-embed ng pagsubok bilang interpreter sessions sa docs	Tinuturing ang mga snippet ng docs bilang normal na Python code para sa pagsubok
Integrasyon	Standard library module	`pytest` plugin para sa walang putol na integrasyon
Syntax ng Pagsubok	`>>>` prompts, pagtutugma ng inaasahang output	Standard na Python code, `pytest` assertions
Flexibilidad	Limitado, mahina ang pagtutugma ng output	Mataas, sumusuporta sa kumplikadong pagsubok, decorators, debugging
Kalinisan ng Dokumentasyon	Maaaring magkalat sa docs dahil sa test mechanics	Nagpapanatili ng malinis na docs gamit ang nakatagong direktiba
Debugging	Paghahambing ng string, hindi direktang inspeksyon	Standard na Python debugging, buong tracebacks
Setup/Teardown	Maaaring magdagdag ng ingay sa mga halimbawa	Epektibong pinamamahalaan ang konteksto gamit ang continuation blocks
Pinagmulan ng Katotohanan	Format ng dokumentasyon at nakabaong pagsubok	Markdown source, sinusuri sa pamamagitan ng standard na pagpapatupad ng Python

Ipinapakilala din ng doc-builder ang mga continuation block, isang mahalagang feature para sa mga multi-step na tutorial. Nagbibigay-daan ito sa mga may-akda na hatiin ang isang halimbawa sa maraming nakikitang snippet, tulad ng runnable:test_basic na sinusundan ng runnable:test_basic:2. Mahalaga, ang mga block na ito ay nagbabahagi ng parehong execution context sa panahon ng pagsubok, na nagpapagana ng isang natural na instructional flow nang hindi pinipilit ang lahat ng code sa isang mahabang block. Ang flexibility na ito ay mahalaga para sa paggabay sa mga user sa kumplikadong paggamit ng modelo ng AI o mga pipeline ng pagproseso ng data.

Halimbawa, ang isang workflow sa pagbuo ng AI agent ay maaaring may ilang hakbang: pagtukoy sa mga tool ng agent, pag-initialize ng agent, at pagkatapos ay pagpapatakbo ng query. Pinapayagan ng mga continuation block na maipakita ang bawat isa sa mga hakbang na ito nang malinaw sa magkahiwalay na seksyon ng dokumentasyon habang isinasagawa bilang isang solong, magkakaugnay na test sequence, katulad ng kung paano ang mga advanced na agentic workflow ay Operationalizing Agentic AI: Part 1.

Pagpapanatili ng Malinaw na Dokumentasyon Habang Tinitiyak ang Matibay na Pagsubok

Ang isa sa mga pinaka-eleganteng solusyon ng doc-builder ay ang kakayahan nitong panatilihing malinis ang na-render na dokumentasyon, kahit na ang pinagmulan ng Markdown ay naglalaman ng mga direktiba na partikular sa pagsubok. Maaaring mag-embed ang mga developer ng mga komento tulad ng # doc-builder: hide para sa mga naisasagawang linya na hindi dapat lumabas sa dokumentasyon, o # doc-builder: ignore-bare-assert para sa mga assertion na bahagi ng pagsubok ngunit ang komento ay hindi dapat i-render. Katulad nito, ang mga pytest decorator (# pytest-decorator: ...) ay tinatanggal sa panahon ng rendering.

Tinitiyak nito na nananatiling nakatuon ang dokumentasyon sa pagtuturo at kalinawan, nang hindi nagkakalat ng testing boilerplate. Nakikita lang ng user ang nauugnay na code, habang ginagarantiya ng pinagbabatayang sistema ang functionality nito. Ang balanse na ito ay kritikal para sa dokumentasyon ng mga tool ng developer, kung saan parehong mahalaga ang aesthetic appeal at ang ganap na kawastuhan.

Epekto sa Malalaking Proyekto ng AI at Higit Pa

Para sa napakalaking repository tulad ng Transformers ng Hugging Face, na may daan-daang pahina ng dokumentasyon at libu-libong halimbawa, ang feature na ito ay transformative. Awtomatiko nitong pinipigilan ang paglihis ng dokumentasyon, isang problema na kung hindi ay mangangailangan ng napakalaking manu-manong pagsisikap o magreresulta sa isang tuloy-tuloy na daloy ng mga sirang halimbawa. Tumutulong ang runnable documentation na panatilihing magkasabay ang dokumentasyon at codebase, na pinapanatili ang pagiging mapagkakatiwalaan sa isang sukat kung saan ang manu-manong pagsusuri ay hindi na praktikal. Nakaayon ito sa mas malawak na pagsisikap sa komunidad ng AI na mahigpit na Sinusuri ang Mga Ahente ng AI para sa Produksyon at tiyakin ang pagiging maaasahan.

Sa pamamagitan ng pagdadala ng naisasagawang dokumentasyon sa modernong panahon ng pytest at sopistikadong CI/CD pipelines, ipinapakita ng Hugging Face ang isang makapangyarihang pangako sa karanasan ng developer at kalidad ng code. Ang layunin ay nananatiling pareho tulad ng dalawang dekada na ang nakalipas: ang mga halimbawa ng dokumentasyon ay dapat gumana. Ngunit ngayon, hindi lamang nila inilalarawan kung paano dapat gumana ang code kundi patuloy din nilang pinapatunayan na ito ay gumagana, na nagpapalago ng isang mas maaasahan at mapagkakatiwalaang ecosystem para sa pagbuo ng AI.

Orihinal na pinagmulan

https://huggingface.co/blog/huggingface/runnable-examples

Mga Karaniwang Tanong

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.

Manatiling Updated

Kunin ang pinakabagong AI news sa iyong inbox.

I-share