Når den gjengis, vises denne blokken som et standard kodeeksempel. Under testing blir den imidlertid utført som vanlig Python-kode. Denne doble naturen sikrer at dokumentasjonen forblir ren for lesere, samtidig som den gir robuste, testbare eksempler for utviklere. Denne tilnærmingen er spesielt virkningsfull for intrikate domener som AI, der eksempler ofte involverer komplekse modellinnlastings- og inferensetrinn.
## Sømløs integrasjon med `pytest` og avanserte funksjoner
En viktig differensiator for Hugging Faces tilnærming er dens sømløse integrasjon med moderne testrammeverk, spesielt `pytest`. Med `hf-doc-builder` installert kan `pytest` automatisk oppdage og utføre kjørbare blokker innenfor Markdown-filer, og behandle hver blokk som et standard testelement. Dette betyr at dokumentasjonseksempler fullt ut kan delta i et prosjekts eksisterende testinfrastruktur, og utnytte `pytest`s kraftige funksjoner som påstander, fixtures, feilsøkingsverktøy og omfattende rapportering.
### Utviklingen av eksekverbar dokumentasjon: `doctest` vs. `doc-builder`
| Funksjon | `doctest` (Tradisjonell) | `doc-builder` (Moderne kjørbar Markdown) |
| :------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **Testtilnærming** | Legger inn tester som tolkingsøkter i dokumenter | Behandler dokumentsnutter som vanlig Python-kode for testing |
| **Integrasjon** | Standard bibliotekmodul | `pytest`-plugin for sømløs integrasjon |
| **Testsyntaks** | `>>>`-prompter, samsvarende forventet utdata | Standard Python-kode, `pytest`-påstander |
| **Fleksibilitet** | Begrenset, skjør utdatamatching | Høy, støtter komplekse tester, dekoratører, feilsøking |
| **Dokumentasjonsrenhet** | Kan rotete til dokumenter med testmekanismer | Bevarer rene dokumenter med skjulte direktiver |
| **Feilsøking** | Strengsammenligning, mindre direkte inspeksjon | Standard Python-feilsøking, fullstendige sporingslogger |
| **Oppsett/Nedrigging** | Kan legge støy til eksempler | Håndterer kontekst effektivt med kontinueringsblokker |
| **Sannhetskilde** | Dokumentasjonsformat og innebygde tester | Markdown-kilde, testet via standard Python-utførelse |
Doc-builder introduserer også **kontinueringsblokker**, en avgjørende funksjon for veiledninger med flere trinn. Disse lar forfattere dele et eksempel over flere synlige kodebiter, som `runnable:test_basic` etterfulgt av `runnable:test_basic:2`. Avgjørende er at disse blokkene deler samme utførelseskontekst under tester, noe som muliggjør en naturlig instruksjonsflyt uten å tvinge all kode inn i én lang blokk. Denne fleksibiliteten er avgjørende for å veilede brukere gjennom kompleks AI-modellbruk eller databehandlingspipeliner.
For eksempel kan en arbeidsflyt for utvikling av AI-agenter involvere flere trinn: definering av agentens verktøy, initialisering av agenten og deretter kjøring av en spørring. Kontinueringsblokker lar hvert av disse trinnene presenteres tydelig i separate dokumentasjonsseksjoner, samtidig som de utføres som en enkelt, sammenhengende testsekvens, lignende hvordan avanserte agentiske arbeidsflyter er [Operationalizing Agentic AI: Part 1](/no/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Opprettholde ren dokumentasjon samtidig som robust testing sikres
En av 'doc-builder's mest elegante løsninger er dens evne til å holde den gjengitte dokumentasjonen ren, selv når kilde-Markdown inneholder testspesifikke direktiver. Utviklere kan legge inn kommentarer som `# doc-builder: hide` for kjørbare linjer som ikke skal vises i dokumentasjonen, eller `# doc-builder: ignore-bare-assert` for påstander som er en del av testen, men hvis kommentar ikke skal gjengis. På samme måte fjernes `pytest`-dekoratører (`# pytest-decorator: ...`) under gjengivelsen.
Dette sikrer at dokumentasjonen forblir fokusert på læring og klarhet, uten å bli rotete av test-boilerplate. Brukeren ser kun den relevante koden, mens det underliggende systemet garanterer dens funksjonalitet. Denne balansen er avgjørende for dokumentasjon av utviklerverktøy, der både estetisk appell og absolutt korrekthet er av største betydning.
## Påvirkning på store AI-prosjekter og videre
For massive repositorier som Hugging Faces Transformers, med hundrevis av dokumentasjonssider og tusenvis av eksempler, er denne funksjonen transformerende. Den automatiserer forebygging av dokumentasjonsdrift, et problem som ellers ville kreve enorm manuell innsats eller ført til en konstant strøm av ødelagte eksempler. Kjørbar dokumentasjon bidrar til å holde dokumentasjonen og kodebasen synkronisert, og opprettholder troverdighet i en skala der manuell gjennomgang rett og slett er ugjennomførbar. Dette samsvarer med bredere innsats i AI-miljøet for å grundig [Evaluating AI Agents for Production](/no/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) og sikre pålitelighet.
Ved å bringe eksekverbar dokumentasjon inn i den moderne æraen med `pytest` og sofistikerte CI/CD-pipelines, demonstrerer Hugging Face en sterk forpliktelse til utvikleropplevelse og kodekvalitet. Målet forblir det samme som for over to tiår siden: dokumentasjonseksempler skal fungere. Men nå illustrerer de ikke bare hvordan kode *burde* fungere, men *beviser* kontinuerlig at den gjør det, og fremmer et mer pålitelig og troverdig økosystem for AI-utvikling.
Opprinnelig kilde
https://huggingface.co/blog/huggingface/runnable-examplesOfte stilte spørsmål
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.
Hold deg oppdatert
Få de siste AI-nyhetene i innboksen din.