Oluşturulduğunda, bu blok standart bir kod örneği olarak görünür. Ancak test sırasında, normal Python kodu olarak yürütülür. Bu ikili yapı, dokümantasyonun okuyucular için temiz kalmasını sağlarken, geliştiriciler için sağlam, test edilebilir örnekler sunar. Bu yaklaşım, örneklerin genellikle karmaşık model yükleme ve çıkarım adımlarını içerdiği yapay zeka gibi karmaşık alanlar için özellikle etkilidir.
## `pytest` ve Gelişmiş Özelliklerle Sorunsuz Entegrasyon
Hugging Face yaklaşımının temel ayırt edici özelliği, modern test çerçeveleri, özellikle `pytest` ile sorunsuz entegrasyonudur. `hf-doc-builder` yüklendiğinde, `pytest` Markdown dosyalarındaki çalıştırılabilir blokları otomatik olarak keşfedebilir ve yürütebilir, her bloğu standart bir test öğesi olarak ele alır. Bu, dokümantasyon örneklerinin bir projenin mevcut test altyapısına tam olarak katılabileceği anlamına gelir; `pytest`'in iddialar, fixture'lar, hata ayıklama araçları ve kapsamlı raporlama gibi güçlü özelliklerinden yararlanabilirler.
### Çalıştırılabilir Dokümantasyonun Evrimi: `doctest` ve `doc-builder`
| Özellik | `doctest` (Geleneksel) | `doc-builder` (Modern Çalıştırılabilir Markdown) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **Test Yaklaşımı** | Dokümanlara yorumlayıcı oturumları olarak testler gömer | Doküman parçacıklarını test için normal Python kodu olarak ele alır |
| **Entegrasyon** | Standart kütüphane modülü | Sorunsuz entegrasyon için `pytest` eklentisi |
| **Test Sözdizimi** | `>>>` istemleri, beklenen çıktı eşleştirme | Standart Python kodu, `pytest` iddiaları |
| **Esneklik** | Sınırlı, kırılgan çıktı eşleştirme | Yüksek, karmaşık testleri, dekoratörleri, hata ayıklamayı destekler |
| **Dokümantasyon Temizliği** | Test mekaniği ile dokümanları karıştırabilir | Gizli yönergelerle temiz dokümanları korur |
| **Hata Ayıklama** | Dize karşılaştırma, daha az doğrudan inceleme | Standart Python hata ayıklama, tam izleme yığınları |
| **Kurulum/Kaldırma** | Örneklere gürültü ekleyebilir | Devam bloklarıyla bağlamı etkili bir şekilde yönetir |
| **Doğruluk Kaynağı** | Dokümantasyon formatı ve gömülü testler | Markdown kaynağı, standart Python yürütmesi yoluyla test edilir |
`doc-builder` ayrıca, çok adımlı öğreticiler için kritik bir özellik olan **devam bloklarını** da sunar. Bunlar, yazarların bir örneği `runnable:test_basic` ve ardından `runnable:test_basic:2` gibi birden çok görünür parçacığa bölmesine olanak tanır. En önemlisi, bu bloklar testler sırasında aynı yürütme bağlamını paylaşır, tüm kodu tek bir uzun bloğa zorlamadan doğal bir öğretim akışı sağlar. Bu esneklik, kullanıcıları karmaşık yapay zeka modeli kullanımı veya veri işleme pipeline'ları aracılığıyla yönlendirmek için hayati öneme sahiptir.
Örneğin, bir yapay zeka ajanı geliştirme iş akışı birkaç adım içerebilir: ajanın araçlarını tanımlama, ajanı başlatma ve ardından bir sorgu çalıştırma. Devam blokları, bu adımların her birinin ayrı dokümantasyon bölümlerinde açıkça sunulmasına olanak tanırken, gelişmiş ajanik iş akışlarının [Ajan Temelli Yapay Zekayı Operasyonelleştirme: Bölüm 1](/tr/operationalizing-agentic-ai-part-1-a-stakeholders-guide) benzer şekilde tek, tutarlı bir test dizisi olarak yürütülmesini sağlar.
## Sağlam Test Sağlarken Temiz Dokümantasyonu Sürdürme
`doc-builder`'ın en zarif çözümlerinden biri, kaynak Markdown test özel direktifleri içerse bile oluşturulan dokümantasyonu temiz tutma yeteneğidir. Geliştiriciler, dokümantasyonda görünmemesi gereken çalıştırılabilir satırlar için `# doc-builder: hide` veya testin bir parçası olan ancak yorumu oluşturulmaması gereken iddialar için `# doc-builder: ignore-bare-assert` gibi yorumları gömebilirler. Benzer şekilde, `pytest` dekoratörleri (`# pytest-decorator: ...`) oluşturma sırasında çıkarılır.
Bu, dokümantasyonun test kalıbıyla karıştırılmadan öğretmeye ve netliğe odaklanmasını sağlar. Kullanıcı sadece ilgili kodu görürken, temel sistem işlevselliğini garanti eder. Bu denge, hem estetik çekiciliğin hem de mutlak doğruluğun çok önemli olduğu geliştirici araçları dokümantasyonu için kritik öneme sahiptir.
## Büyük Ölçekli Yapay Zeka Projeleri ve Ötesi Üzerindeki Etki
Yüzlerce dokümantasyon sayfası ve binlerce örneği olan Hugging Face'ın Transformers gibi devasa depolar için bu özellik dönüştürücüdür. Aksi takdirde muazzam manuel çaba gerektirecek veya sürekli bir bozuk örnek akışına yol açacak bir sorun olan dokümantasyon sapmasını otomatik olarak önler. Çalıştırılabilir dokümantasyon, dokümantasyon ve kod tabanını senkronize tutmaya yardımcı olarak, manuel incelemenin mümkün olmadığı bir ölçekte güvenilirliği sürdürür. Bu, yapay zeka topluluğunda [Üretim İçin Yapay Zeka Ajanlarını Değerlendirme](/tr/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) ve güvenilirliği sağlama konusundaki daha geniş çabalarla uyumludur.
Çalıştırılabilir dokümantasyonu `pytest` ve gelişmiş CI/CD pipeline'larının modern çağına taşıyarak, Hugging Face geliştirici deneyimine ve kod kalitesine güçlü bir bağlılık göstermektedir. Amaç, yirmi yıldan uzun bir süre önce olduğu gibi aynı kalmaktadır: dokümantasyon örnekleri çalışmalıdır. Ancak şimdi, kodun nasıl çalışması gerektiğini sadece göstermekle kalmıyor, aynı zamanda sürekli olarak çalıştığını *kanıtlıyor*, yapay zeka geliştirme için daha güvenilir ve güvenilir bir ekosistem besliyor.
Orijinal kaynak
https://huggingface.co/blog/huggingface/runnable-examplesSık Sorulan Sorular
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.
Güncel Kalın
En son yapay zeka haberlerini e-postanıza alın.