Uitvoerbare Markdown: Revolusionêre Dokumentasietoetsing met Hugging Face

Dokumentasie dien as die kritieke brug tussen ontwikkelaars en hul gereedskap, maar die betroubaarheid daarvan word dikwels ondermyn deur 'n deurdringende kwessie: dokumentasie-drywing. Namate sagteware ontwikkel, kan kodevoorbeelde in dokumentasie stilweg breek, wat lei tot frustrasie, verlore tyd en 'n erosie van vertroue. Hugging Face, 'n leier in KI-innovasie, spreek hierdie uitdaging direk aan met sy doc-builder-projek, wat uitvoerbare Markdown-blokke bekendstel wat verseker dat dokumentasievoorbeelde nie net illustratief is nie, maar streng getoets word. Hierdie moderne benadering herdefinieer hoe ons uitvoerbare dokumentasie benader, en versmelt die duidelikheid van goeie dokumente met die robuustheid van kontinue toetsing.

Die Uitdaging: Oorbrugging van Dokumentasie en Kode-integriteit

Die kernfilosofie agter uitvoerbare dokumentasie is nie nuut nie. Vir dekades het die Python-gemeenskap gepleit vir voorbeelde in dokumentasie wat gebruikers kan kopieer, plak en verwag om foutloos te loop. Die handhawing van hierdie ideaal oor groot, vinnig ontwikkelende projekte soos Hugging Face se Transformers-biblioteek is egter 'n monumentale taak. Handmatige verifikasie is onprakties, en tradisionele metodes dwing dikwels 'n kompromie tussen duidelike dokumentasie en effektiewe toetsing af.

Die probleem spruit voort uit die fundamentele verskille in vereistes:

Dokumentasievoorbeelde prioritiseer bondigheid, leesbaarheid en 'n fokus op onderrig. Hulle streef daarna om vry van "geraas" te wees.
Toetse vereis bewerings, opstelling/afbreking, fixtures, nabootsing en ontfoutingsvermoëns. Hulle prioritiseer robuustheid en dekking.

Wanneer hierdie twee bekommernisse in dieselfde formaat gedwing word, ly een dikwels. Hugging Face se doc-builder poog om hierdie spanning op te los deur dokumentasie skoon te laat bly terwyl die onderliggende voorbeelde streng gevalideer word, en sodoende te verseker dat elke snips wat gebruikers teëkom 'n verifieerbare waarheid is, nie net 'n aspirasie nie. Dit is van kardinale belang vir die handhawing van geloofwaardigheid en die versnelling van ontwikkelaarstoepassing in die vinnige wêreld van KI.

Die Nalatenskap van `doctest`: Vroeë Innovasies en Ontwikkelende Behoeftes

Die konsep van uitvoerbare dokumentasie het vroeg in Python aanklank gevind met die bekendstelling van doctest in Python 2.1 (2001). Geskep deur Tim Peters, was doctest 'n elegante oplossing: dit het dokumentasievoorbeelde wat soos interaktiewe Python-interpreteerdersessies geformateer is (>>> add(2, 3)\n5) geparseer en geverifieer dat die uitset aan die verwagtinge voldoen. Hierdie innovasie het dokumentasievoorbeelde in outomatiese regressietoetse verander, 'n beduidende sprong vorentoe vir kodekwaliteit.

doctest was besonder goed geskik vir Python, 'n taal wat interaktiewe eksplorasie aangemoedig het. Vir klein projekte en eenvoudige API's het dit uitsonderlik goed gewerk, en 'n eenvoudige dog kragtige meganisme verskaf om te verseker dat basiese voorbeelde funksioneel bly. Dit het die gees van "wys, moenie net vertel nie" in sagteware-ontwikkeling beliggaam, wat dokumentasie 'n aktiewe deel van die toetsreeks gemaak het.

Hugging Face se Moderne Oplossing: Uitvoerbare Markdown-blokke

Met die erkenning van die beperkinge van ouer benaderings vir grootskaalse, komplekse projekte, stel Hugging Face se doc-builder-projek 'n gesofistikeerde benadering tot uitvoerbare dokumentasie bekend. In plaas daarvan om toetse binne dokumentasiesintaks in te bed, behandel dit dokumentasiesnipse as gewone Python-kode wat binne Markdown lê. Dit verander Markdown effektief in 'n dun toetskontainer, wat die aanbieding van die toetsmetodologie ontkoppel.

’n Uitvoerbare blok in Markdown lyk soos volg:

```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


Wanneer dit weergegee word, verskyn hierdie blok as 'n standaard kodevoorbeeld. Tydens toetsing word dit egter as normale Python-kode uitgevoer. Hierdie dubbele aard verseker dat dokumentasie skoon bly vir lesers terwyl dit robuuste, toetsbare voorbeelde vir ontwikkelaars bied. Hierdie benadering is veral impakvol vir ingewikkelde domeine soos KI, waar voorbeelde dikwels komplekse modelle wat laai en afleidingsstappe behels.

## Naatlose Integrasie met `pytest` en Gevorderde Kenmerke

’n Sleutelonderskeidende kenmerk van Hugging Face se benadering is die naatlose integrasie daarvan met moderne toetsraamwerke, veral `pytest`. Met `hf-doc-builder` geïnstalleer, kan `pytest` outomaties uitvoerbare blokke binne Markdown-lêers ontdek en uitvoer, en elke blok as 'n standaardtoetselement behandel. Dit beteken dat dokumentasievoorbeelde ten volle kan deelneem aan 'n projek se bestaande toetsinfrastruktuur, deur `pytest` se kragtige kenmerke soos bewerings, fixtures, ontfoutingshulpmiddels en omvattende verslagdoening te benut.

### Die Evolusie van Uitvoerbare Dokumentasie: `doctest` teenoor `doc-builder`

| Kenmerk                   | `doctest` (Tradisioneel)                               | `doc-builder` (Moderne Uitvoerbare Markdown)           |
| :------------------------ | :----------------------------------------------------- | :----------------------------------------------------- |
| **Toetsbenadering**       | Bed in toetse as interpreteerdersessies in dokumente | Behandel dokumentsnipse as normale Python-kode vir toetsing |
| **Integrasie**            | Standaard biblioteekmodule                             | `pytest`-invoegtoepassing vir naatlose integrasie      |
| **Toetssintaks**          | `>>>` aanwysings, verwagte uitsetpassing              | Standaard Python-kode, `pytest`-bevestigings           |
| **Buigsaamheid**          | Beperk, brose uitsetpassing                            | Hoog, ondersteun komplekse toetse, versierders, ontfouting |
| **Dokumentasie Netheid**  | Kan dokumente vol toetstegnieke maak                  | Behou skoon dokumente met versteekte direktiewe        |
| **Ontfouting**            | Stringvergelyking, minder direkte inspeksie           | Standaard Python-ontfouting, volle spoornasporings     |
| **Opstelling/Afbreking**  | Kan geraas by voorbeelde voeg                         | Bestuur konteks effektief met voortsettingsblokke      |
| **Bron van Waarheid**     | Dokumentasieformaat en ingebedde toetse               | Markdown-bron, getoets via standaard Python-uitvoering |

Die `doc-builder` stel ook **voortsettingsblokke** bekend, 'n deurslaggewende kenmerk vir meerstaptutoriale. Dit stel outeurs in staat om 'n voorbeeld oor verskeie sigbare snipse te verdeel, soos `runnable:test_basic` gevolg deur `runnable:test_basic:2`. Dit is van kardinale belang dat hierdie blokke dieselfde uitvoeringskonteks tydens toetse deel, wat 'n natuurlike instruksionele vloei moontlik maak sonder om alle kode in een lang blok te dwing. Hierdie buigsaamheid is noodsaaklik vir die leiding van gebruikers deur komplekse KI-modelgebruik of dataverwerkingspypleidings.

Byvoorbeeld, 'n KI-agentontwikkelingswerkvloei kan verskeie stappe behels: die definisie van die agent se gereedskap, die inisialisering van die agent, en dan die uitvoering van 'n navraag. Voortsettingsblokke laat toe dat elk van hierdie stappe duidelik in afsonderlike dokumentasieafdelings aangebied word terwyl dit as 'n enkele, samehangende toetsreeks uitgevoer word, soortgelyk aan hoe gevorderde agentiese werkvloeie is [Operationalizing Agentic AI: Part 1](/af/operationalizing-agentic-ai-part-1-a-stakeholders-guide).

## Handhawing van Skoon Dokumentasie terwyl Robuuste Toetsing Verseker Word

Een van `doc-builder` se mees elegante oplossings is sy vermoë om die weergegee dokumentasie skoon te hou, selfs wanneer die bron-Markdown toetsspesifieke direktiewe bevat. Ontwikkelaars kan kommentaar soos `# doc-builder: hide` vir uitvoerbare lyne wat nie in die dokumentasie moet verskyn nie, of `# doc-builder: ignore-bare-assert` vir bewerings wat deel van die toets is maar waarvan die kommentaar nie weergegee moet word nie, direk inbed. Soortgelyk word `pytest`-versierders (`# pytest-decorator: ...`) tydens weergawe verwyder.

Dit verseker dat die dokumentasie gefokus bly op onderrig en duidelikheid, sonder om vol te wees met toets-standaardformules. Die gebruiker sien slegs die relevante kode, terwyl die onderliggende stelsel die funksionaliteit daarvan waarborg. Hierdie balans is van kritieke belang vir ontwikkelaarsgereedskap-dokumentasie, waar beide estetiese aantrekkingskrag en absolute korrektheid van uiterste belang is.

## Impak op Grootskaalse KI-projekte en Verder

Vir massiewe bewaarplekke soos Hugging Face se Transformers, met honderde dokumentasiebladsye en duisende voorbeelde, is hierdie kenmerk transformatief. Dit outomatiseer die voorkoming van dokumentasie-drywing, 'n probleem wat andersins enorme handmatige inspanning sou vereis of sou lei tot 'n konstante stroom van gebroke voorbeelde. Uitvoerbare dokumentasie help om die dokumentasie en kodebasis in sinkronisasie te hou, wat betroubaarheid handhaaf op 'n skaal waar handmatige hersiening eenvoudig onhaalbaar is. Dit strook met breër pogings in die KI-gemeenskap om rigoureus [Evaluating AI Agents for Production](/af/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) te evalueer en betroubaarheid te verseker.

Deur uitvoerbare dokumentasie in die moderne era van `pytest` en gesofistikeerde CI/CD-pypleidings te bring, demonstreer Hugging Face 'n kragtige verbintenis tot ontwikkelaarervaring en kodekwaliteit. Die doel bly dieselfde as twee dekades gelede: dokumentasievoorbeelde behoort te werk. Maar nou illustreer hulle nie net hoe kode *behoort* te werk nie, maar *bewys* voortdurend dat dit werk, wat 'n meer betroubare en geloofwaardige ekosisteem vir KI-ontwikkeling bevorder.

Oorspronklike bron

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

Gereelde Vrae

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.

Bly op hoogte

Kry die nuutste KI-nuus in jou inkassie.

Deel