رَن ایبل مارک ڈاؤن: ہگنگ فیس کے ساتھ ڈاکومینٹیشن ٹیسٹنگ میں انقلاب

ڈاکومینٹیشن ڈویلپرز اور ان کے ٹولز کے درمیان ایک اہم پل کا کام کرتی ہے، لیکن اس کی وشوسنییتا اکثر ایک عام مسئلے کی وجہ سے متاثر ہوتی ہے: ڈاکومینٹیشن ڈرفٹ۔ جیسے جیسے سافٹ ویئر ارتقاء پذیر ہوتا ہے، ڈاکومینٹیشن میں کوڈ کی مثالیں خاموشی سے ٹوٹ سکتی ہیں، جس سے مایوسی، وقت کا ضیاع، اور اعتماد میں کمی واقع ہوتی ہے۔ ہگنگ فیس، جو AI جدت میں ایک رہنما ہے، اپنے doc-builder پروجیکٹ کے ساتھ اس چیلنج کا براہ راست مقابلہ کر رہی ہے، جس میں رَن ایبل مارک ڈاؤن بلاکس متعارف کرائے گئے ہیں جو اس بات کو یقینی بناتے ہیں کہ ڈاکومینٹیشن کی مثالیں صرف توضیحی نہیں بلکہ سختی سے جانچی گئی ہوں۔ یہ جدید طریقہ کار اس بات کی از سر نو تعریف کرتا ہے کہ ہم قابل عمل ڈاکومینٹیشن کو کیسے دیکھتے ہیں، اچھی دستاویزات کی وضاحت کو مسلسل جانچ کی مضبوطی کے ساتھ ضم کرتا ہے۔

چیلنج: ڈاکومینٹیشن اور کوڈ کی سالمیت کو جوڑنا

رَن ایبل ڈاکومینٹیشن کے پیچھے کا بنیادی فلسفہ نیا نہیں ہے۔ کئی دہائیوں سے، Python کمیونٹی نے ڈاکومینٹیشن میں ایسی مثالوں کی وکالت کی ہے جنہیں صارفین کاپی کر سکتے ہیں، پیسٹ کر سکتے ہیں اور بغیر کسی خرابی کے چلنے کی توقع کر سکتے ہیں۔ تاہم، ہگنگ فیس کی ٹرانسفارمرز لائبریری جیسے بڑے، تیزی سے ترقی پذیر پروجیکٹس میں اس مثالی کو برقرار رکھنا ایک یادگار کام ہے۔ دستی توثیق غیر عملی ہے، اور روایتی طریقے اکثر واضح ڈاکومینٹیشن اور مؤثر جانچ کے درمیان سمجھوتہ کرنے پر مجبور کرتے ہیں۔

مسئلہ بنیادی اختلافات سے پیدا ہوتا ہے:

ڈاکومینٹیشن کی مثالیں اختصار، پڑھنے کی اہلیت، اور تعلیم پر توجہ کو ترجیح دیتی ہیں۔ ان کا مقصد 'شور' سے پاک ہونا ہے۔
ٹیسٹ دعووں، سیٹ اپ/ٹیئر ڈاؤن، فکسچرز، موکنگ، اور ڈیبگنگ کی صلاحیتوں کا مطالبہ کرتے ہیں۔ وہ مضبوطی اور کوریج کو ترجیح دیتے ہیں۔

جب ان دونوں خدشات کو ایک ہی فارمیٹ میں مجبور کیا جاتا ہے، تو اکثر ایک کو نقصان پہنچتا ہے۔ ہگنگ فیس کا doc-builder اس تناؤ کو حل کرنے کا ارادہ رکھتا ہے تاکہ ڈاکومینٹیشن کو صاف ستھرا رکھا جا سکے جبکہ اس کی بنیادی مثالوں کو سختی سے توثیق کیا جا سکے، اس بات کو یقینی بناتے ہوئے کہ ہر ٹکڑا جو صارفین کو ملتا ہے وہ ایک قابل تصدیق حقیقت ہے، نہ کہ صرف ایک خواہش۔ یہ AI کی تیز رفتار دنیا میں ساکھ کو برقرار رکھنے اور ڈویلپر کی قبولیت کو تیز کرنے کے لیے اہم ہے۔

`doctest` کی میراث: ابتدائی اختراعات اور ابھرتی ہوئی ضروریات

قابل عمل ڈاکومینٹیشن کا تصور Python میں doctest کی Python 2.1 (2001) میں شمولیت کے ساتھ ابتدائی کشش حاصل کی۔ ٹم پیٹرز نے تیار کردہ، doctest ایک خوبصورت حل تھا: یہ انٹرایکٹو Python انٹرپریٹر سیشنز (>>> add(2, 3)\n5) کی طرح فارمیٹ کردہ ڈاکومینٹیشن کی مثالوں کو پارس کرتا تھا اور اس بات کی تصدیق کرتا تھا کہ آؤٹ پٹ توقعات کے مطابق ہے۔ اس اختراع نے ڈاکومینٹیشن کی مثالوں کو خودکار ریگریشن ٹیسٹ میں بدل دیا، جو کوڈ کے معیار کے لیے ایک اہم پیش رفت تھی۔

doctest خاص طور پر Python کے لیے موزوں تھا، ایک ایسی زبان جو انٹرایکٹو ایکسپلوریشن کی حوصلہ افزائی کرتی ہے۔ چھوٹے پروجیکٹس اور سیدھے سادے APIs کے لیے، اس نے غیر معمولی طور پر اچھا کام کیا، بنیادی مثالوں کو فعال رکھنے کے لیے ایک سادہ لیکن طاقتور طریقہ کار فراہم کیا۔ اس نے سافٹ ویئر ڈیولپمنٹ میں "صرف بتائیں نہیں، دکھائیں" کے جذبے کو مجسم کیا، ڈاکومینٹیشن کو ٹیسٹنگ سوٹ کا ایک فعال حصہ بنایا۔

ہگنگ فیس کا جدید حل: رَن ایبل مارک ڈاؤن بلاکس

بڑے پیمانے پر، پیچیدہ پروجیکٹس کے لیے پرانے طریقوں کی حدود کو تسلیم کرتے ہوئے، ہگنگ فیس کا doc-builder پروجیکٹ رَن ایبل ڈاکومینٹیشن پر ایک نفیس طریقہ متعارف کراتا ہے۔ ڈاکومینٹیشن کے نحو کے اندر ٹیسٹوں کو شامل کرنے کے بجائے، یہ ڈاکومینٹیشن کے ٹکڑوں کو مارک ڈاؤن کے اندر موجود عام Python کوڈ کے طور پر لیتا ہے۔ یہ مؤثر طریقے سے مارک ڈاؤن کو ایک پتلی ٹیسٹ کنٹینر میں بدل دیتا ہے، جس سے پیشکش کو جانچ کے طریقہ کار سے الگ کیا جاتا ہے۔

مارک ڈاؤن میں ایک رَن ایبل بلاک کچھ یوں نظر آتا ہے:

```py runnable:quickstart
from transformers import pipeline

pipe = pipeline("sentiment-analysis")
result = pipe("I love runnable docs!")

if not result:  # doc-builder: hide
    raise ValueError("pipeline returned no result")

print(result[0]["label"])
assert result[0]["score"] > 0.5  # doc-builder: ignore-bare-assert
```

جب رینڈر کیا جاتا ہے، تو یہ بلاک ایک معیاری کوڈ مثال کے طور پر ظاہر ہوتا ہے۔ تاہم، جانچ کے دوران، یہ عام Python کوڈ کے طور پر ایگزیکیوٹ ہوتا ہے۔ یہ دوہری نوعیت اس بات کو یقینی بناتی ہے کہ ڈاکومینٹیشن قارئین کے لیے صاف رہے جبکہ ڈویلپرز کے لیے مضبوط، ٹیسٹ ایبل مثالیں فراہم کی جا سکیں۔ یہ طریقہ کار خاص طور پر AI جیسے پیچیدہ ڈومینز کے لیے اثر انگیز ہے، جہاں مثالوں میں اکثر پیچیدہ ماڈل لوڈنگ اور انفرنس کے مراحل شامل ہوتے ہیں۔

`pytest` اور جدید خصوصیات کے ساتھ ہموار انٹیگریشن

ہگنگ فیس کے طریقہ کار کا ایک اہم امتیازی عنصر جدید ٹیسٹنگ فریم ورک، خاص طور پر pytest کے ساتھ اس کی ہموار انٹیگریشن ہے۔ hf-doc-builder انسٹال ہونے کے بعد، pytest خود بخود مارک ڈاؤن فائلوں کے اندر رَن ایبل بلاکس کو تلاش اور ایگزیکیوٹ کر سکتا ہے، ہر بلاک کو ایک معیاری ٹیسٹ آئٹم کے طور پر لیتا ہے۔ اس کا مطلب ہے کہ ڈاکومینٹیشن کی مثالیں ایک پروجیکٹ کے موجودہ ٹیسٹ انفراسٹرکچر میں پوری طرح سے حصہ لے سکتی ہیں، pytest کی طاقتور خصوصیات جیسے دعویٰ کے میکانزم، فکسچرز، ڈیکوریٹرز، اور ڈیبگنگ ٹولز کا فائدہ اٹھاتے ہوئے کر سکتی ہیں۔ ناکامیاں جامع ٹریس بیکس کے ساتھ عام ٹیسٹ کی ناکامیوں کے طور پر ظاہر ہوتی ہیں، جس سے ڈویلپرز کو مؤثر طریقے سے ڈیبگ کرنے کی اجازت ملتی ہے۔

قابل عمل ڈاکومینٹیشن کا ارتقاء: `doctest` بمقابلہ `doc-builder`

خصوصیت	`doctest` (روایتی)	`doc-builder` (جدید رَن ایبل مارک ڈاؤن)
ٹیسٹنگ کا طریقہ کار	ٹیسٹوں کو انٹرپریٹر سیشنز کے طور پر ڈاکس میں شامل کرتا ہے	ڈاکس کے ٹکڑوں کو جانچ کے لیے نارمل Python کوڈ کے طور پر لیتا ہے
انٹیگریشن	معیاری لائبریری ماڈیول	ہموار انٹیگریشن کے لیے `pytest` پلگ ان
ٹیسٹ کا نحو	`>>>` پرامپٹس، متوقع آؤٹ پٹ مماثلت	معیاری Python کوڈ، `pytest` دعوے
لچک	محدود، خراب آؤٹ پٹ مماثلت	اعلیٰ، پیچیدہ ٹیسٹوں، ڈیکوریٹرز، ڈیبگنگ کو سپورٹ کرتا ہے
ڈاکومینٹیشن کی صفائی	ٹیسٹ میکانکس سے ڈاکس کو بھر سکتا ہے	پوشیدہ ہدایات کے ساتھ صاف ڈاکس کو برقرار رکھتا ہے
ڈیبگنگ	سٹرنگ کا موازنہ، کم براہ راست معائنہ	معیاری Python ڈیبگنگ، مکمل ٹریس بیکس
سیٹ اپ/ٹیئر ڈاؤن	مثالوں میں شور شامل کر سکتا ہے	تسلسلی بلاکس کے ساتھ تناظر کو مؤثر طریقے سے منظم کرتا ہے
سچائی کا ماخذ	ڈاکومینٹیشن فارمیٹ اور ایمبیڈڈ ٹیسٹ	مارک ڈاؤن سورس، معیاری Python ایگزیکیوشن کے ذریعے جانچا گیا

doc-builder تسلسلی بلاکس (continuation blocks) بھی متعارف کراتا ہے، جو کثیر مرحلہ کے ٹیوٹوریلز کے لیے ایک اہم خصوصیت ہے۔ یہ مصنفین کو ایک مثال کو متعدد مرئی ٹکڑوں میں تقسیم کرنے کی اجازت دیتے ہیں، جیسے runnable:test_basic جس کے بعد runnable:test_basic:2۔ اہم بات یہ ہے کہ یہ بلاکس ٹیسٹوں کے دوران ایک ہی ایگزیکیوشن تناظر کو شیئر کرتے ہیں، جو تمام کوڈ کو ایک لمبے بلاک میں ڈالنے پر مجبور کیے بغیر ایک قدرتی تدریسی بہاؤ کو ممکن بناتے ہیں۔ یہ لچک صارفین کو پیچیدہ AI ماڈل کے استعمال یا ڈیٹا پروسیسنگ پائپ لائنوں کے ذریعے رہنمائی کرنے کے لیے اہم ہے۔

مثال کے طور پر، ایک AI ایجنٹ کی ترقی کے ورک فلو میں کئی مراحل شامل ہو سکتے ہیں: ایجنٹ کے ٹولز کی وضاحت، ایجنٹ کو شروع کرنا، اور پھر ایک سوال چلانا۔ تسلسلی بلاکس ان میں سے ہر ایک مرحلے کو ڈاکومینٹیشن کے الگ الگ حصوں میں واضح طور پر پیش کرنے کی اجازت دیتے ہیں جبکہ انہیں ایک واحد، مربوط ٹیسٹ سیکونس کے طور پر ایگزیکیوٹ کیا جاتا ہے، اسی طرح جیسے جدید ایجنٹک ورک فلو آپریشنلائزنگ ایجنٹک AI: حصہ 1 ہیں۔

مضبوط جانچ کو یقینی بناتے ہوئے ڈاکومینٹیشن کو صاف ستھرا رکھنا

doc-builder کے سب سے خوبصورت حلوں میں سے ایک یہ ہے کہ وہ رینڈر کردہ ڈاکومینٹیشن کو صاف ستھرا رکھنے کی صلاحیت رکھتا ہے، چاہے سورس مارک ڈاؤن میں ٹیسٹ کے لیے مخصوص ہدایات شامل ہوں۔ ڈویلپرز # doc-builder: hide جیسے تبصرے قابل عمل لائنوں کے لیے شامل کر سکتے ہیں جو ڈاکومینٹیشن میں ظاہر نہیں ہونی چاہئیں، یا # doc-builder: ignore-bare-assert ان دعووں کے لیے جو ٹیسٹ کا حصہ ہیں لیکن جن کا تبصرہ رینڈر نہیں ہونا چاہیے۔ اسی طرح، pytest ڈیکوریٹرز (# pytest-decorator: ...) رینڈرنگ کے دوران ہٹا دیے جاتے ہیں۔

یہ اس بات کو یقینی بناتا ہے کہ ڈاکومینٹیشن تعلیم اور وضاحت پر مرکوز رہے، بغیر ٹیسٹنگ بوائلر پلیٹ سے بھری ہو۔ صارف صرف متعلقہ کوڈ دیکھتا ہے، جبکہ بنیادی نظام اس کی فعالیت کی ضمانت دیتا ہے۔ ڈویلپر ٹولز کی ڈاکومینٹیشن کے لیے یہ توازن اہم ہے، جہاں جمالیاتی اپیل اور مطلق درستگی دونوں کی ضرورت ہے۔

بڑے پیمانے پر AI پروجیکٹس اور اس سے آگے پر اثر

ہگنگ فیس کے ٹرانسفارمرز جیسے بڑے ذخیروں کے لیے، جس میں سینکڑوں ڈاکومینٹیشن صفحات اور ہزاروں مثالیں ہیں، یہ خصوصیت انقلابی ہے۔ یہ ڈاکومینٹیشن ڈرفٹ کی روک تھام کو خودکار بناتا ہے، ایک ایسا مسئلہ جسے بصورت دیگر بے پناہ دستی کوشش کی ضرورت ہوتی یا ٹوٹے ہوئے مثالوں کے مستقل سلسلے کا باعث بنتا۔ رَن ایبل ڈاکومینٹیشن ڈاکومینٹیشن اور کوڈ بیس کو ہم آہنگ رکھنے میں مدد کرتا ہے، اس پیمانے پر اعتماد کو برقرار رکھتا ہے جہاں دستی جائزہ محض ناممکن ہے۔ یہ AI کمیونٹی میں ایجنٹوں کو سختی سے پیداوار کے لیے AI ایجنٹوں کا اندازہ لگانا اور وشوسنییتا کو یقینی بنانے کی وسیع کوششوں کے مطابق ہے۔

قابل عمل ڈاکومینٹیشن کو pytest اور جدید CI/CD پائپ لائنوں کے جدید دور میں لا کر، ہگنگ فیس ڈویلپر کے تجربے اور کوڈ کے معیار کے لیے ایک طاقتور عزم کا مظاہرہ کرتا ہے۔ ہدف وہی ہے جو دو دہائیوں سے زیادہ پہلے تھا: ڈاکومینٹیشن کی مثالوں کو کام کرنا چاہیے۔ لیکن اب، وہ نہ صرف یہ بتاتے ہیں کہ کوڈ کو کیسے کام کرنا چاہیے بلکہ مسلسل یہ ثابت کرتے ہیں کہ یہ کام کرتا ہے، جو AI ڈیولپمنٹ کے لیے ایک زیادہ قابل اعتماد اور قابل بھروسہ ایکو سسٹم کو فروغ دیتا ہے۔

اصل ماخذ

https://huggingface.co/blog/huggingface/runnable-examples

اکثر پوچھے جانے والے سوالات

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.

اپ ڈیٹ رہیں

تازہ ترین AI خبریں اپنے ان باکس میں حاصل کریں۔

شیئر کریں