Kur shfaqet, ky bllok shfaqet si një shembull kodi standard. Gjatë testimit, megjithatë, ai ekzekutohet si kod normal Python. Kjo natyrë e dyfishtë siguron që dokumentacioni të mbetet i pastër për lexuesit, duke ofruar njëkohësisht shembuj të fortë dhe të testueshëm për zhvilluesit. Kjo qasje është veçanërisht ndikuese për fusha të ndërlikuara si AI, ku shembujt shpesh përfshijnë ngarkim kompleks të modeleve dhe hapa inferencë.
## Integrim Pa Probleme me `pytest` dhe Veçori të Avancuara
Një diferencues kyç i qasjes së Hugging Face është integrimi i saj pa probleme me kornizat moderne të testimit, veçanërisht `pytest`. Me `hf-doc-builder` të instaluar, `pytest` mund të zbulojë dhe ekzekutojë automatikisht blloqe të ekzekutueshme brenda skedarëve Markdown, duke trajtuar çdo bllok si një element standard testimi. Kjo do të thotë që shembujt e dokumentacionit mund të marrin pjesë plotësisht në infrastrukturën ekzistuese të testimit të një projekti, duke shfrytëzuar veçoritë e fuqishme të `pytest` si mekanizmat e pohimit, fiksturat, dekoratorët dhe mjetet e debugimit. Dështimet shfaqen si dështime normale testimi me gjurmë të plota, duke i lejuar zhvilluesit të debugojnë në mënyrë efektive.
### Evolucioni i Dokumentacionit të Ekzekutueshëm: `doctest` vs. `doc-builder`
| Veçori | `doctest` (Tradicional) | `doc-builder` (Markdown Modern i Ekzekutueshëm) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Qasja e Testimit** | Ngulit testet si sesione interpretuesi në dokumente | Trajton copëzat e dokumentacionit si kod normal Python për testim |
| **Integrimi** | Modul i bibliotekës standarde | Plugin `pytest` për integrim pa probleme |
| **Sintaksa e Testit** | Kërkesat `>>>`, përputhja e daljes së pritshme | Kod standard Python, pohimet `pytest` |
| **Fleksibiliteti** | I kufizuar, përputhje e brishtë e daljes | I lartë, mbështet teste komplekse, dekoratorë, debugim |
| **Pastërtia e Dokumentacionit**| Mund të mbushë dokumentet me mekanizma testimi | Ruaj dokumentet e pastra me direktiva të fshehura |
| **Debugimi** | Krahasimi i stringjeve, inspektim më pak i drejtpërdrejtë | Debugim standard Python, gjurmë të plota |
| **Konfigurim/Çmontim** | Mund të shtojë zhurmë në shembuj | Menaxhon kontekstin në mënyrë efektive me blloqe vazhdimi |
| **Burimi i së Vërtetës** | Formati i dokumentacionit dhe testet e ngulitura | Burimi Markdown, i testuar nëpërmjet ekzekutimit standard Python |
`doc-builder` prezanton gjithashtu **blloket e vazhdimit** (continuation blocks), një veçori thelbësore për udhëzuesit me shumë hapa. Këto u lejojnë autorëve të ndajnë një shembull nëpër copëza të shumta të dukshme, si `runnable:test_basic` e ndjekur nga `runnable:test_basic:2`. Ç'është më e rëndësishmja, këto blloqe ndajnë të njëjtin kontekst ekzekutimi gjatë testeve, duke mundësuar një rrjedhë natyrale udhëzuese pa detyruar të gjithë kodin në një bllok të gjatë. Kjo fleksibilitet është jetik për të udhëhequr përdoruesit përmes përdorimit kompleks të modeleve AI ose tubacioneve të përpunimit të të dhënave.
Për shembull, një rrjedhë pune e zhvillimit të agjentëve AI mund të përfshijë disa hapa: përcaktimin e mjeteve të agjentit, inicializimin e agjentit dhe më pas ekzekutimin e një kërkese. Blloket e vazhdimit lejojnë që secili nga këta hapa të paraqitet qartë në seksione të veçanta të dokumentacionit, ndërsa ekzekutohen si një sekuencë testimi e vetme, kohezive, ngjashëm me mënyrën se si rrjedhat e avancuara agjentike janë [Operacionalizimi i AI Agjentike: Pjesa 1](/sq/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## Mbajtja e Dokumentacionit të Pastër duke Siguruar Testim të Fortë
Një nga zgjidhjet më elegante të `doc-builder` është aftësia e tij për të mbajtur të pastër dokumentacionin e paraqitur, edhe kur burimi Markdown përmban direktiva specifike për test. Zhvilluesit mund të ngulitin komente si `# doc-builder: hide` për rreshtat e ekzekutueshëm që nuk duhet të shfaqen në dokumentacion, ose `# doc-builder: ignore-bare-assert` për pohimet që janë pjesë e testit, por komenti i të cilave nuk duhet të shfaqet. Ngjashëm, dekoratorët `pytest` (`# pytest-decorator: ...`) hiqen gjatë shfaqjes.
Kjo siguron që dokumentacioni të mbetet i fokusuar në mësimdhënie dhe qartësi, pa u mbushur me shabllone testimi. Përdoruesi sheh vetëm kodin përkatës, ndërsa sistemi themelor garanton funksionalitetin e tij. Kjo balancë është kritike për dokumentacionin e mjeteve të zhvilluesve, ku si apeli estetik ashtu edhe saktësia absolute janë thelbësore.
## Ndikimi në Projektet e Mëdha të AI dhe Përtej tyre
Për depozita masive si Transformers e Hugging Face, me qindra faqe dokumentacioni dhe mijëra shembuj, kjo veçori është transformuese. Ajo automatizon parandalimin e shmangies së dokumentacionit, një problem që përndryshe do të kërkonte një sasi të jashtëzakonshme përpjekjesh manuale ose do të çonte në një rrjedhë të vazhdueshme shembujsh të dëmtuar. Dokumentacioni i ekzekutueshëm ndihmon në mbajtjen e dokumentacionit dhe bazës së kodit në sinkron, duke ruajtur besueshmërinë në një shkallë ku rishikimi manual është thjesht i pamundur. Kjo është në përputhje me përpjekjet më të gjera në komunitetin e AI për [Vlerësimin e Agjentëve AI për Prodhime](/sq/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) dhe sigurimin e besueshmërisë.
Duke sjellë dokumentacionin e ekzekutueshëm në epokën moderne të `pytest` dhe tubacioneve të sofistikuara CI/CD, Hugging Face demonstron një angazhim të fuqishëm ndaj përvojës së zhvilluesve dhe cilësisë së kodit. Qëllimi mbetet i njëjtë siç ishte mbi dy dekada më parë: shembujt e dokumentacionit duhet të funksionojnë. Por tani, ata jo vetëm ilustrojnë se si kodi *duhet* të funksionojë, por vazhdimisht *provëzojnë* që ai funksionon, duke nxitur një ekosistem më të besueshëm dhe të besueshëm për zhvillimin e AI.
Burimi origjinal
https://huggingface.co/blog/huggingface/runnable-examplesPyetjet e bëra shpesh
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.
Qëndroni të përditësuar
Merrni lajmet më të fundit të AI në email.