Þegar þessi blokk er birt, birtist hún sem venjulegt kóðadæmi. Við prófun er hún hins vegar keyrð sem venjulegur Python kóði. Þessi tvíþætta eðli tryggir að skjöl haldist hrein fyrir lesendur á sama tíma og veitir öflug, prófanleg dæmi fyrir forritara. Þessi nálgun er sérstaklega áhrifarík fyrir flókin svið eins og gervigreind, þar sem dæmi fela oft í sér flókna módellestur og ályktunarskref.
## Óaðfinnanleg samþætting við `pytest` og háþróaða eiginleika
Lykilatriði sem aðgreinir nálgun Hugging Face er óaðfinnanleg samþætting hennar við nútíma prófunarumhverfi, sérstaklega `pytest`. Með uppsettri `hf-doc-builder` getur `pytest` sjálfkrafa fundið og keyrt keyranlegar blokkir innan Markdown skráa, og meðhöndlað hverja blokk sem staðlaðan prófunarhlut. Þetta þýðir að dæmi í skjölum geta tekið fullan þátt í núverandi prófunarinnviðum verkefnisins, og nýtt sér öfluga eiginleika `pytest` eins og staðfestingar, fixtures, decorators, villuleitartól og ítarlega skýrslugerð.
### Þróun keyranlegra skjala: `doctest` á móti `doc-builder`
| Eiginleiki | `doctest` (Hefðbundin) | `doc-builder` (Nútíma keyranleg Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Prófunaraðferð** | Felur próf sem túlkaþing í skjölum | Meðhöndlar skjalaútbrot sem venjulegan Python kóða til prófunar |
| **Samþætting** | Staðlað safnaeining | `pytest` viðbót fyrir óaðfinnanlega samþættingu |
| **Prófunarfrágangur** | `>>>` hvatningar, jöfnun væntanlegs úttaks | Staðlaður Python kóði, `pytest` staðfestingar |
| **Sveigjanleiki** | Takmarkaður, brothætt úttaksjöfnun | Mikill, styður flókin próf, decorators, villuleit |
| **Hreinleiki skjala** | Getur truflað skjöl með prófunarvirkni | Varðveitir hrein skjöl með földum leiðbeiningum |
| **Villuleit** | Strengjasamanburður, minni bein skoðun | Staðlað Python villuleit, fullur rekjaum |
| **Uppsetning/Niðurrif** | Getur bætt 'hávaða' við dæmi | Stjórnar samhengi á áhrifaríkan hátt með framhaldsblokkum |
| **Uppruni sannleika** | Skjalaform og innfelld próf | Markdown frumkóði, prófaður með venjulegri Python keyrslu |
`doc-builder` kynnir einnig **framhaldsblokkir**, sem er mikilvægur eiginleiki fyrir fjölþrepa kennsluefni. Þær gera höfundum kleift að skipta dæmi yfir í marga sýnilega bút, eins og `runnable:test_basic` fylgt eftir af `runnable:test_basic:2`. Mikilvægt er að þessar blokkir deila sama keyrslu samhengi við prófun, sem gerir kleift að fá náttúrulegt kennsluflæði án þess að neyða allan kóða inn í eina langa blokk. Þessi sveigjanleiki er mikilvægur til að leiðbeina notendum í gegnum flókna notkun gervigreindarlíkana eða gagnvinnslu pípur.
Til dæmis gæti vinnuflæði fyrir gervigreindartáknþróun falið í sér nokkur skref: skilgreiningu á verkfærum táknsins, frumstillingu táknsins og síðan keyrslu á fyrirspurn. Framhaldsblokkir gera kleift að kynna hvert þessara skrefa skýrt í aðskildum skjalamöppuhlutum á sama tíma og þau eru keyrð sem ein, samfelld prófunarröð, svipað og hvernig háþróuð táknrænu vinnuflæði eru [Gervigreindartákn í rekstri: Hluti 1](/is/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Viðhald á hreinum skjölum á sama tíma og tryggð er öflug prófun
Ein glæsilegasta lausn `doc-builder` er hæfni þess til að halda birtum skjölum hreinum, jafnvel þegar upprunaleg Markdown inniheldur prófunarsértækar leiðbeiningar. Forritarar geta fellt inn athugasemdir eins og `# doc-builder: hide` fyrir keyranlegar línur sem ættu ekki að birtast í skjölum, eða `# doc-builder: ignore-bare-assert` fyrir staðfestingar sem eru hluti af prófinu en athugasemd þeirra ætti ekki að birtast. Á sama hátt eru `pytest` decorators (`# pytest-decorator: ...`) fjarlægðir við birtingu.
Þetta tryggir að skjöl haldist einbeitt að kennslu og skýrleika, án þess að vera yfirfull af prófunarviðbótum. Notandinn sér aðeins viðeigandi kóða, á meðan undirliggjandi kerfi ábyrgist virkni hans. Þetta jafnvægi er mikilvægt fyrir skjöl verkfæra forritara, þar sem bæði fagurfræðileg aðdráttarafl og alger réttmæti eru mikilvægust.
## Áhrif á stór gervigreindarverkefni og víðar
Fyrir stórar geymslur eins og Transformers frá Hugging Face, með hundruðum skjalamöppusíðna og þúsundum dæma, er þessi eiginleiki umbreytandi. Hann sjálfvirkar forvarnir gegn skjalafrádrætti (documentation drift), vandamáli sem annars myndi krefjast gríðarlegrar handvirkrar vinnu eða leiða til stöðugs straums af brotnum dæmum. Keyranleg skjöl hjálpa til við að halda skjölum og kóðagrunni í samræmi, og viðhalda trúverðugleika á mælikvarða þar sem handvirk yfirferð er einfaldlega óframkvæmanleg. Þetta samræmist víðtækari viðleitni í gervigreindarsamfélaginu til að nákvæmlega [Meta gervigreindartákn fyrir framleiðslu](/is/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) og tryggja áreiðanleika.
Með því að færa keyranlega skjalamöppu inn í nútíma tímabil `pytest` og flókinna CI/CD pípa, sýnir Hugging Face öfluga skuldbindingu við upplifun forritara og kóðagæði. Markmiðið er það sama og það var fyrir rúmum tveimur áratugum: dæmi í skjölum ættu að virka. En nú, sýna þau ekki aðeins hvernig kóði *ætti* að virka heldur *sanna* þau stöðugt að hann gerir það, og stuðla þannig að áreiðanlegra og trúverðugra vistkerfi fyrir gervigreindarþróun.
Upprunaleg heimild
https://huggingface.co/blog/huggingface/runnable-examplesAlgengar spurningar
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.
Fylgstu með
Fáðu nýjustu gervigreindarfréttirnar í pósthólfið.