Kada se renderira, ovaj blok se pojavljuje kao standardni primjer koda. Međutim, tijekom testiranja, izvršava se kao normalan Python kod. Ova dvostruka priroda osigurava da dokumentacija ostane čista za čitatelje, dok pruža robusne primjere koji se mogu testirati za razvojne programere. Ovaj pristup je posebno značajan za složena područja poput umjetne inteligencije, gdje primjeri često uključuju složeno učitavanje modela i korake zaključivanja.
## Besprijekorna integracija s `pytest`-om i naprednim značajkama
Ključna razlika Hugging Faceovog pristupa je njegova besprijekorna integracija s modernim testnim okvirima, posebno `pytest`-om. S instaliranim `hf-doc-builder`-om, `pytest` može automatski otkriti i izvršiti izvršive blokove unutar Markdown datoteka, tretirajući svaki blok kao standardnu testnu stavku. To znači da primjeri dokumentacije mogu u potpunosti sudjelovati u postojećoj testnoj infrastrukturi projekta, koristeći `pytest`-ove moćne značajke poput provjera, fixture-a, alata za otklanjanje pogrešaka i sveobuhvatnog izvještavanja.
### Evolucija izvršive dokumentacije: `doctest` vs. `doc-builder`
| Značajka | `doctest` (Tradicionalni) | `doc-builder` (Moderni izvršivi Markdown) |
| :--------------------------- | :---------------------------------------------------- | :---------------------------------------------------- |
| **Pristup testiranju** | Ugrađuje testove kao sesije interpreter-a u dokumente | Tretira isječke dokumentacije kao normalan Python kod za testiranje |
| **Integracija** | Standardni modul biblioteke | `pytest` dodatak za besprijekornu integraciju |
| **Sintaksa testa** | `>>>` upiti, podudaranje očekivanog izlaza | Standardni Python kod, `pytest` provjere |
| **Fleksibilnost** | Ograničeno, krhko podudaranje izlaza | Visoka, podržava složene testove, dekoratore, otklanjanje pogrešaka |
| **Čistoća dokumentacije** | Može pretrpati dokumente testnim mehanikama | Čuva čiste dokumente s skrivenim direktivama |
| **Otklanjanje pogrešaka** | Usporedba nizova, manje izravna inspekcija | Standardno otklanjanje pogrešaka u Pythonu, puni tragovi poziva |
| **Postavljanje/čišćenje** | Može dodati šum primjerima | Učinkovito upravlja kontekstom s blokovima za nastavak |
| **Izvor istine** | Format dokumentacije i ugrađeni testovi | Markdown izvor, testiran putem standardnog Python izvršavanja |
`doc-builder` također uvodi **blokove za nastavak** (continuation blocks), ključnu značajku za višestupanjske tutorijale. Oni omogućuju autorima da podijele primjer na više vidljivih isječaka, poput `runnable:test_basic` nakon čega slijedi `runnable:test_basic:2`. Ključno je da ti blokovi dijele isti kontekst izvršavanja tijekom testova, omogućujući prirodan tok podučavanja bez prisiljavanja cijelog koda u jedan dugi blok. Ova fleksibilnost je vitalna za vođenje korisnika kroz složenu upotrebu AI modela ili cjevovode za obradu podataka.
Na primjer, tijek rada za razvoj AI agenta mogao bi uključivati nekoliko koraka: definiranje alata agenta, inicijalizaciju agenta, a zatim pokretanje upita. Blokovi za nastavak omogućuju da se svaki od ovih koraka jasno prikaže u zasebnim odjeljcima dokumentacije, dok se izvršavaju kao jedinstvena, kohezivna testna sekvenca, slično načinu na koji su napredni agentni tijekovi rada [Operacionalizacija agentne umjetne inteligencije: 1. dio](/hr/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Održavanje čiste dokumentacije uz osiguravanje robusnog testiranja
Jedno od najelegantnijih rješenja `doc-builder`-a je njegova sposobnost da zadrži renderiranu dokumentaciju čistom, čak i kada izvorni Markdown sadrži direktive specifične za testiranje. Razvojni programeri mogu ugraditi komentare poput `# doc-builder: hide` za izvršive retke koji se ne bi trebali pojaviti u dokumentaciji, ili `# doc-builder: ignore-bare-assert` za provjere koje su dio testa, ali čiji se komentar ne bi trebao renderirati. Slično tome, `pytest` dekoratori (`# pytest-decorator: ...`) uklanjaju se tijekom renderiranja.
Time se osigurava da dokumentacija ostane usredotočena na podučavanje i jasnoću, bez da je pretrpana testnim boilerplate kodom. Korisnik vidi samo relevantan kod, dok temeljni sustav jamči njegovu funkcionalnost. Ova ravnoteža je ključna za dokumentaciju razvojnih alata, gdje su estetska privlačnost i apsolutna ispravnost od najveće važnosti.
## Utjecaj na AI projekte velikih razmjera i šire
Za masivna spremišta poput Hugging Faceovih Transformersa, sa stotinama stranica dokumentacije i tisućama primjera, ova je značajka transformativna. Automatizira sprječavanje zastarijevanja dokumentacije, problem koji bi inače zahtijevao ogroman ručni napor ili bi doveo do stalnog protoka neispravnih primjera. Izvršiva dokumentacija pomaže u sinkronizaciji dokumentacije i baze koda, održavajući povjerenje u razmjerima gdje je ručni pregled jednostavno neizvediv. To je u skladu sa širim naporima u AI zajednici za rigorozno [Evaluaciju AI agenata za produkciju](/hr/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) i osiguravanje pouzdanosti.
Donošenjem izvršive dokumentacije u moderno doba `pytest`-a i sofisticiranih CI/CD cjevovoda, Hugging Face demonstrira snažnu predanost korisničkom iskustvu razvojnih programera i kvaliteti koda. Cilj ostaje isti kao i prije više od dva desetljeća: primjeri u dokumentaciji trebaju raditi. Ali sada, oni ne samo da ilustriraju kako kod *treba* raditi, već kontinuirano *dokazuju* da radi, potičući pouzdaniji ekosustav za razvoj umjetne inteligencije.
Često postavljana pitanja
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.
Budite u toku
Primajte najnovije AI vijesti na e-mail.