عند العرض، تظهر هذه الكتلة كمثال تعليمات برمجية قياسي. ومع ذلك، أثناء الاختبار، يتم تنفيذها كتعليمات برمجية Python عادية. تضمن هذه الطبيعة المزدوجة أن يظل التوثيق نظيفًا للقراء بينما يوفر أمثلة قوية وقابلة للاختبار للمطورين. وهذا النهج مؤثر بشكل خاص في المجالات المعقدة مثل الذكاء الاصطناعي، حيث تتضمن الأمثلة غالبًا خطوات معقدة لتحميل النماذج والاستدلال.
## التكامل السلس مع `pytest` والميزات المتقدمة
أحد الاختلافات الرئيسية في نهج Hugging Face هو تكامله السلس مع أطر الاختبار الحديثة، وخاصة `pytest`. مع تثبيت `hf-doc-builder`، يمكن لـ `pytest` اكتشاف وتنفيذ الكتل القابلة للتشغيل تلقائيًا داخل ملفات Markdown، والتعامل مع كل كتلة كعنصر اختبار قياسي. وهذا يعني أن أمثلة التوثيق يمكنها الاستفادة من القوة الكاملة لـ `pytest`، بما في ذلك آليات التأكيد، والمثبتات (fixtures)، والمُزخرفات (decorators)، وأدوات تصحيح الأخطاء. تظهر الإخفاقات كإخفاقات اختبار عادية مع آثار تتبع شاملة، مما يسمح للمطورين بتصحيح الأخطاء بفعالية.
### تطور التوثيق القابل للتنفيذ: `doctest` مقابل `doc-builder`
| الميزة | `doctest` (التقليدي) | `doc-builder` (Markdown العصري القابل للتشغيل) |
| :------------------------- | :------------------------------------------------------ | :---------------------------------------------------- |
| **نهج الاختبار** | يضمِّن الاختبارات كجلسات مترجم في التوثيق | يتعامل مع مقتطفات التوثيق كتعليمات برمجية Python عادية للاختبار |
| **التكامل** | وحدة مكتبة قياسية | مكون `pytest` إضافي (plugin) لتكامل سلس |
| **بناء جملة الاختبار** | `>>>` مطالبات، مطابقة الإخراج المتوقع | تعليمات برمجية Python قياسية، تأكيدات `pytest` |
| **المرونة** | محدودة، مطابقة إخراج هشة | عالية، تدعم الاختبارات المعقدة، المُزخرفات (decorators)، التصحيح |
| **نظافة التوثيق** | يمكن أن يربك التوثيق بآليات الاختبار | يحافظ على التوثيق النظيف بتوجيهات مخفية |
| **تصحيح الأخطاء** | مقارنة السلاسل، فحص أقل مباشرة | تصحيح أخطاء Python قياسي، آثار تتبع كاملة |
| **الإعداد/التفكيك** | يمكن أن يضيف ضوضاء إلى الأمثلة | يدير السياق بفعالية باستخدام كتل الاستمرارية |
| **مصدر الحقيقة** | تنسيق التوثيق والاختبارات المضمنة | مصدر Markdown، تم اختباره عبر تنفيذ Python قياسي |
يقدم `doc-builder` أيضًا **كتل الاستمرارية**، وهي ميزة حاسمة للدروس التعليمية متعددة الخطوات. تسمح هذه للمؤلفين بتقسيم مثال عبر مقتطفات مرئية متعددة، مثل `runnable:test_basic` يليه `runnable:test_basic:2`. الأهم من ذلك، أن هذه الكتل تشترك في نفس سياق التنفيذ أثناء الاختبارات، مما يتيح تدفقًا تعليميًا طبيعيًا دون إجبار جميع التعليمات البرمجية على كتلة واحدة طويلة. هذه المرونة حيوية لتوجيه المستخدمين خلال استخدام نماذج الذكاء الاصطناعي المعقدة أو مسارات معالجة البيانات.
على سبيل المثال، يمكن أن تتضمن سير عمل تطوير وكيل ذكاء اصطناعي عدة خطوات: تحديد أدوات الوكيل، وتهيئة الوكيل، ثم تشغيل استعلام. تسمح كتل الاستمرارية بتقديم كل من هذه الخطوات بوضوح في أقسام توثيق منفصلة بينما يتم تنفيذها كتسلسل اختبار واحد متماسك، على غرار كيفية [تشغيل الذكاء الاصطناعي الوكيل: الجزء الأول](/ar/operationalizing-agentic-ai-part-1-a-stakeholders-guide).
## الحفاظ على توثيق نظيف مع ضمان اختبار قوي
أحد أكثر الحلول أناقة في `doc-builder` هو قدرته على الحفاظ على التوثيق المعروض نظيفًا، حتى عندما يحتوي مصدر Markdown على توجيهات خاصة بالاختبار. يمكن للمطورين تضمين تعليقات مثل `# doc-builder: hide` للأسطر القابلة للتنفيذ التي لا يجب أن تظهر في التوثيق، أو `# doc-builder: ignore-bare-assert` للتأكيدات التي هي جزء من الاختبار ولكن لا يجب عرض تعليقها. وبالمثل، يتم تجريد مُزخرفات `pytest` (`# pytest-decorator: ...`) أثناء العرض.
يضمن ذلك أن يظل التوثيق مركزًا على التدريس والوضوح، دون أن يتلوث بآليات الاختبار المكررة. يرى المستخدم التعليمات البرمجية ذات الصلة فقط، بينما يضمن النظام الأساسي وظائفها. هذا التوازن أمر بالغ الأهمية لتوثيق أدوات المطورين، حيث يكون الجاذبية الجمالية والدقة المطلقة على حد سواء في غاية الأهمية.
## التأثير على مشاريع الذكاء الاصطناعي واسعة النطاق وما بعدها
بالنسبة للمستودعات الضخمة مثل Hugging Face Transformers، التي تحتوي على مئات صفحات التوثيق وآلاف الأمثلة، تعد هذه الميزة تحويلية. فهي تعمل على أتمتة منع انحراف التوثيق، وهي مشكلة كانت ستتطلب بخلاف ذلك جهدًا يدويًا هائلًا أو تؤدي إلى تيار مستمر من الأمثلة المعطلة. يساعد التوثيق القابل للتشغيل في الحفاظ على تزامن التوثيق وقاعدة التعليمات البرمجية، والحفاظ على الموثوقية على نطاق حيث تكون المراجعة اليدوية ببساطة غير ممكنة. وهذا يتوافق مع الجهود الأوسع في مجتمع الذكاء الاصطناعي لـ [تقييم وكلاء الذكاء الاصطناعي للإنتاج](/ar/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) وضمان الموثوقية.
من خلال جلب التوثيق القابل للتنفيذ إلى العصر الحديث لـ `pytest` ومسارات CI/CD المتطورة، تظهر Hugging Face التزامًا قويًا بتجربة المطور وجودة التعليمات البرمجية. يبقى الهدف كما كان قبل عقدين من الزمن: يجب أن تعمل أمثلة التوثيق. ولكن الآن، لا تكتفي بتوضيح كيف *يجب* أن تعمل التعليمات البرمجية فحسب، بل *تثبت* باستمرار أنها تعمل، مما يعزز نظامًا بيئيًا أكثر موثوقية وجدارة بالثقة لتطوير الذكاء الاصطناعي.
الأسئلة الشائعة
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.
ابقَ على اطلاع
احصل على آخر أخبار الذكاء الاصطناعي في بريدك.