Ko je izrisan, se ta blok prikaže kot standardni primer kode. Med testiranjem pa se izvede kot običajna Python koda. Ta dvojna narava zagotavlja, da dokumentacija ostane čista za bralce, hkrati pa razvijalcem zagotavlja robustne, preizkusljive primere. Ta pristop je še posebej učinkovit za zapletene domene, kot je umetna inteligenca, kjer primeri pogosto vključujejo kompleksno nalaganje modelov in korake sklepanja.
## Brezhibna integracija s `pytestom` in naprednimi funkcijami
Ključna značilnost pristopa podjetja Hugging Face je njegova brezhibna integracija s sodobnimi testnimi ogrodji, zlasti s `pytestom`. Ko je `hf-doc-builder` nameščen, lahko `pytest` samodejno odkrije in izvede izvedljive bloke v datotekah Markdown, pri čemer vsak blok obravnava kot standardni testni element. To pomeni, da lahko primeri dokumentacije v celoti sodelujejo v obstoječi testni infrastrukturi projekta, izkoriščajoč zmogljive funkcije `pytesta`, kot so preverjanje, fixtures, dekoraterji in celovito poročanje.
### Evolucija izvedljive dokumentacije: `doctest` v primerjavi z `doc-builder`
| Funkcija | `doctest` (Tradicionalno) | `doc-builder` (Sodobni izvedljivi Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Pristop testiranja** | Vdeluje teste kot seje tolmača v dokumentacijo | Obravnava delčke dokumentacije kot običajno Python kodo za testiranje |
| **Integracija** | Standardni knjižnični modul | Vtičnik `pytest` za brezhibno integracijo |
| **Sintaksa testa** | Navodila `>>>`, ujemanje pričakovanega izhoda | Standardna Python koda, `pytest` trditve |
| **Prilagodljivost** | Omejeno, krhko ujemanje izhoda | Visoka, podpira kompleksne teste, dekoraterje, odpravljanje napak |
| **Čistost dokumentacije**| Lahko prenatrpa dokumentacijo z mehaniko testiranja | Ohranja čisto dokumentacijo s skritimi direktivami |
| **Odpravljanje napak** | Primerjava nizov, manj neposreden pregled | Standardno Python odpravljanje napak, celotne sledi klicev |
| **Nastavitev/čiščenje** | Lahko doda šum primerom | Učinkovito upravlja kontekst z nadaljevalnimi bloki |
| **Vir resnice** | Format dokumentacije in vdelani testi | Markdown vir, testiran z običajno izvedbo Pythona |
`doc-builder` uvaja tudi **nadaljevalne bloke**, ključno funkcijo za večstopenjske vadnice. Ti avtorjem omogočajo, da primer razdelijo med več vidnih delčkov, kot je `runnable:test_basic`, ki mu sledi `runnable:test_basic:2`. Ključno je, da ti bloki med testi delijo isti izvedbeni kontekst, kar omogoča naraven pedagoški tok, ne da bi vso kodo silili v en sam dolg blok. Ta prilagodljivost je ključnega pomena za vodenje uporabnikov skozi kompleksno uporabo modelov AI ali cevovode za obdelavo podatkov.
Na primer, potek dela pri razvoju agenta AI bi lahko vključeval več korakov: definiranje orodij agenta, inicializacijo agenta in nato izvajanje poizvedbe. Nadaljevalni bloki omogočajo, da se vsak od teh korakov jasno predstavi v ločenih razdelkih dokumentacije, medtem ko se izvajajo kot enotno, kohezivno testno zaporedje, podobno kot so napredni agentski poteki dela [Operationalizing Agentic AI: Part 1](/sl/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Ohranjanje čiste dokumentacije ob zagotavljanju robustnega testiranja
Ena izmed najbolj elegantnih rešitev `doc-builderja` je njegova sposobnost ohranjanja čiste izrisane dokumentacije, tudi ko izvorni Markdown vsebuje direktive, specifične za testiranje. Razvijalci lahko vdelajo komentarje, kot je '# doc-builder: hide' za izvedljive vrstice, ki se ne smejo pojaviti v dokumentaciji, ali '# doc-builder: ignore-bare-assert' za trditve, ki so del testa, vendar se njihov komentar ne sme izrisati. Podobno se dekoraterji `pytest` ('# pytest-decorator: ...') odstranijo med izrisovanjem.
To zagotavlja, da dokumentacija ostaja osredotočena na poučevanje in jasnost, ne da bi jo prenatrpala testna rutina. Uporabnik vidi samo relevantno kodo, medtem ko osnovni sistem zagotavlja njeno funkcionalnost. To ravnovesje je ključno za dokumentacijo razvojnih orodij, kjer sta estetska privlačnost in absolutna pravilnost najpomembnejši.
## Vpliv na obsežne projekte umetne inteligence in širše
Za obsežna repozitorija, kot je Hugging Face's Transformers, s stotinami strani dokumentacije in tisočimi primeri, je ta funkcija transformativna. Avtomatizira preprečevanje odmika dokumentacije, problem, ki bi sicer zahteval ogromno ročnega dela ali vodil do stalnega toka pokvarjenih primerov. Izvedljiva dokumentacija pomaga ohranjati sinhronizacijo dokumentacije in kodne baze, ohranja verodostojnost v obsegu, kjer je ročni pregled preprosto neizvedljiv. To se ujema s širšimi prizadevanji v skupnosti AI za rigorozno [Vrednotenje AI agentov za produkcijo](/sl/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) in zagotavljanje zanesljivosti.
Z vnašanjem izvedljive dokumentacije v sodobno dobo `pytesta` in sofisticiranih CI/CD cevovodov, Hugging Face dokazuje močno zavezanost izkušnjam razvijalcev in kakovosti kode. Cilj ostaja enak kot pred več kot dvema desetletjema: primeri v dokumentaciji bi morali delovati. Toda zdaj ne samo ilustrirajo, kako naj bi koda delovala, ampak nenehno *dokazujejo*, da deluje, kar spodbuja zanesljivejši in verodostojnejši ekosistem za razvoj umetne inteligence.
Pogosta vprašanja
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.
Bodite na tekočem
Prejemajte najnovejše AI novice po e-pošti.