Render edildikdə, bu blok standart bir kod nümunəsi kimi görünür. Lakin test zamanı, adi Python kodu kimi icra edilir. Bu ikili təbiət sənədləşdirmənin oxucular üçün təmiz qalmasını təmin edir, eyni zamanda developerlər üçün möhkəm, sınaqdan keçirilə bilən nümunələr təqdim edir. Bu yanaşma, nümunələrin tez-tez mürəkkəb model yükləmə və nəticə çıxarma addımlarını əhatə etdiyi AI kimi mürəkkəb sahələr üçün xüsusilə təsirli olur.
## `pytest` və Qabaqcıl Xüsusiyyətlərlə Problemsiz İnteqrasiya
Hugging Face-in yanaşmasının əsas fərqləndirici cəhəti, müasir test çərçivələri, xüsusilə `pytest` ilə problemsiz inteqrasiyasıdır. `hf-doc-builder` quraşdırıldıqda, `pytest` Markdown fayllarındakı işlək blokları avtomatik olaraq aşkar edə və icra edə bilər, hər bir bloku standart bir test elementi kimi qəbul edir. Bu o deməkdir ki, sənədləşdirmə nümunələri layihənin mövcud test infrastrukturunda tam iştirak edə bilər, `pytest`-in təsdiqləmələr, fiksatorlar, sazlama alətləri və hərtərəfli hesabat kimi güclü xüsusiyyətlərindən istifadə edir.
### İcra Edilə Bilən Sənədləşdirmənin Təkamülü: `doctest` vs. `doc-builder`
| Xüsusiyyət | `doctest` (Ənənəvi) | `doc-builder` (Müasir İşlək Markdown) |
| :--------------------------- | :--------------------------------------------- | :---------------------------------------------------- |
| **Test Yanaşması** | Testləri sənədlərdə interpretator sessiyaları kimi daxil edir | Sənəd fraqmentlərini test üçün adi Python kodu kimi qəbul edir |
| **İnteqrasiya** | Standart kitabxana modulu | `pytest` plagin problemsiz inteqrasiya üçün |
| **Test Sintaksisi** | `>>>` göstərişlər, gözlənilən çıxış uyğunlaşması | Standart Python kodu, `pytest` təsdiqləmələri |
| **Çeviklik** | Məhdud, kövrək çıxış uyğunlaşması | Yüksək, mürəkkəb testləri, dekoratorları, sazlamanı dəstəkləyir |
| **Sənədləşdirmənin Təmizliyi**| Sənədləri test mexanikaları ilə doldura bilər | Gizli direktivlərlə təmiz sənədləri qoruyur |
| **Sazlama** | Sətir müqayisəsi, daha az birbaşa yoxlama | Standart Python sazlaması, tam izləmələr |
| **Qurma/Sökülmə** | Nümunələrə səs-küy əlavə edə bilər | Davamlılıq blokları ilə konteksti effektiv şəkildə idarə edir |
| **Həqiqətin Mənbəyi** | Sənədləşdirmə formatı və daxili testlər | Markdown mənbəyi, standart Python icrası vasitəsilə test edilir |
`doc-builder` həmçinin çoxaddımlı təlimatlar üçün əhəmiyyətli bir xüsusiyyət olan **davamlılıq bloklarını** təqdim edir. Bunlar müəlliflərə bir nümunəni bir neçə görünən fraqmentə bölməyə imkan verir, məsələn, `runnable:test_basic` ardınca `runnable:test_basic:2`. Ən əsası, bu bloklar testlər zamanı eyni icra kontekstini paylaşır, bütün kodu bir uzun bloka məcbur etmədən təbii bir tədris axını təmin edir. Bu çeviklik, istifadəçiləri mürəkkəb AI model istifadəsi və ya məlumat emalı boru kəmərləri vasitəsilə yönləndirmək üçün çox vacibdir.
Məsələn, bir AI agent inkişaf iş axını bir neçə addımı əhatə edə bilər: agentin alətlərini təyin etmək, agenti başlatmaq və sonra bir sorğu icra etmək. Davamlılıq blokları bu addımların hər birini ayrı sənədləşdirmə bölmələrində aydın şəkildə təqdim etməyə imkan verir, eyni zamanda tək, bütöv bir test ardıcıllığı kimi icra edilir, bu da qabaqcıl agent iş axınlarının [Agentik AI-ı Funksionallaşdırmaq: Hissə 1](/az/operationalizing-agentic-ai-part-1-a-stakeholders-guide) necə olduğunu xatırladır.
## Möhkəm Testi Təmin Edərkən Təmiz Sənədləşdirməni Qorumaq
`doc-builder`-in ən zərif həllərindən biri, mənbə Markdown testə xas direktivlər ehtiva etsə belə, render edilmiş sənədləşdirməni təmiz saxlamaq bacarığıdır. Developerlər sənədləşdirmədə görünməməli olan icra edilə bilən sətirlər üçün `# doc-builder: hide` kimi şərhləri və ya testin bir hissəsi olan, lakin şərhi render edilməməli olan təsdiqləmələr üçün `# doc-builder: ignore-bare-assert` şərhlərini daxil edə bilərlər. Eyni şəkildə, `pytest` dekoratorları (`# pytest-decorator: ...`) render zamanı silinir.
Bu, sənədləşdirmənin test şablonları ilə dolu olmadan, tədrisə və aydınlığa yönəlməsini təmin edir. İstifadəçi yalnız müvafiq kodu görür, əsas sistem isə onun funksionallığına zəmanət verir. Bu balans, həm estetik cazibə, həm də mütləq düzgünlüyün əsas olduğu developer alətləri sənədləşdirməsi üçün kritikdir.
## Böyük Miqyaslı AI Layihələrinə və Daha Kənarına Təsiri
Hugging Face-in Transformers kimi yüzlərlə sənədləşdirmə səhifəsi və minlərlə nümunəsi olan böyük repozitoriyaları üçün bu xüsusiyyət dəyişdiricidir. O, sənədləşdirmə sürüşməsinin qarşısını avtomatlaşdırır, əks halda bu problem böyük əl əməyi tələb edər və ya daim xarab nümunələrə gətirib çıxarardı. İşlək sənədləşdirmə, sənədləşdirməni və kod bazasını sinxronizasiyada saxlamağa kömək edir, əl ilə nəzərdən keçirmənin sadəcə qeyri-mümkün olduğu miqyasda etibarlılığı qoruyur. Bu, AI cəmiyyətində [İstehsal üçün AI Agentlərini Qiymətləndirmək](/az/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) və etibarlılığı təmin etmək üçün daha geniş səylərlə uyğun gəlir.
İcra edilə bilən sənədləşdirməni `pytest` və mürəkkəb CI/CD boru kəmərlərinin müasir dövrünə gətirməklə, Hugging Face developer təcrübəsinə və kod keyfiyyətinə güclü bağlılığını nümayiş etdirir. Məqsəd iyirmi ildən çox əvvəl olduğu kimi qalır: sənədləşdirmə nümunələri işləməlidir. Lakin indi onlar yalnız kodun necə *işləməli olduğunu* göstərməklə kifayətlənmir, həm də onun işlədiyini davamlı olaraq *sübut edir*, AI inkişafı üçün daha etibarlı və inamlı bir ekosistem yaradır.
Tez-tez Verilən Suallar
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.
Xəbərdar olun
Ən son AI xəbərlərini e-poçtunuza alın.