مستندات به عنوان پلی حیاتی بین توسعهدهندگان و ابزارهایشان عمل میکند، اما قابلیت اطمینان آن اغلب توسط یک مشکل فراگیر تضعیف میشود: عدم همگامی مستندات. با تکامل نرمافزار، مثالهای کد در مستندات میتوانند بیصدا از کار بیفتند، که منجر به ناامیدی، اتلاف وقت و از بین رفتن اعتماد میشود. Hugging Face، پیشرو در نوآوری هوش مصنوعی، با پروژه doc-builder خود به طور مستقیم به این چالش پرداخته و بلوکهای Markdown قابل اجرا را معرفی کرده است که تضمین میکند مثالهای مستندات نه تنها گویا، بلکه به طور دقیق آزمایش شدهاند. این رویکرد مدرن، نحوه برخورد ما با مستندات اجرایی را بازتعریف میکند و وضوح مستندات خوب را با استحکام تست مداوم در هم میآمیزد.
چالش: پیوند مستندات و یکپارچگی کد
فلسفه اصلی پشت مستندات قابل اجرا جدید نیست. برای دههها، جامعه پایتون از مثالهایی در مستندات حمایت کرده است که کاربران میتوانند آنها را کپی، پیست و انتظار داشته باشند که بیعیب و نقص اجرا شوند. با این حال، حفظ این ایده آل در پروژههای بزرگ و در حال تکامل سریع مانند کتابخانه Transformers از Hugging Face، کاری عظیم است. تأیید دستی غیرعملی است، و روشهای سنتی اغلب مصالحهای بین مستندات واضح و تست مؤثر را تحمیل میکنند.
مشکل از تفاوتهای اساسی در الزامات ناشی میشود:
- مثالهای مستندات به اختصار، خوانایی و تمرکز بر آموزش اولویت میدهند. هدف آنها عاری بودن از "نویز" است.
- تستها به Assertionها، راهاندازی/پایاندهی، Fixtureها، Mocking و قابلیتهای اشکالزدایی نیاز دارند. آنها به استحکام و پوشش اولویت میدهند.
هنگامی که این دو دغدغه در یک قالب واحد اجباری میشوند، اغلب یکی از آنها آسیب میبیند. doc-builder هاگینگ فیس قصد دارد این تنش را با اجازه دادن به مستندات برای بکر ماندن حل کند، در حالی که مثالهای زیرین آن به طور دقیق اعتبارسنجی میشوند و تضمین میشود که هر قطعه کدی که کاربران با آن روبرو میشوند، یک حقیقت قابل تأیید است، نه فقط یک آرزو. این امر برای حفظ اعتبار و تسریع پذیرش توسعهدهندگان در دنیای پرشتاب هوش مصنوعی حیاتی است.
میراث doctest: نوآوریهای اولیه و نیازهای در حال تکامل
مفهوم مستندات اجرایی با معرفی doctest در پایتون 2.1 (2001) در پایتون مورد توجه اولیه قرار گرفت. doctest که توسط Tim Peters ابداع شد، یک راهحل ظریف بود: مثالهای مستندات را که شبیه جلسات مفسر تعاملی پایتون قالببندی شده بودند (>>> add(2, 3)\n5) تجزیه و تحلیل میکرد و تأیید میکرد که خروجی با انتظارات مطابقت دارد. این نوآوری مثالهای مستندات را به تستهای رگرسیون خودکار تبدیل کرد، که یک گام مهم رو به جلو برای کیفیت کد بود.
doctest به ویژه برای پایتون، زبانی که اکتشاف تعاملی را تشویق میکرد، بسیار مناسب بود. برای پروژههای کوچک و APIهای سرراست، به طور استثنایی خوب کار میکرد و مکانیزمی ساده اما قدرتمند برای اطمینان از عملکرد مثالهای اساسی فراهم میکرد. این ابزار روح "نشان بده، فقط نگو" را در توسعه نرمافزار تجسم بخشید و مستندات را به بخشی فعال از مجموعه تست تبدیل کرد.
راهحل مدرن Hugging Face: بلوکهای مارکداون قابل اجرا
با درک محدودیتهای رویکردهای قدیمی برای پروژههای پیچیده و در مقیاس بزرگ، پروژه doc-builder هاگینگ فیس رویکردی پیچیده به مستندات قابل اجرا را معرفی میکند. به جای جاسازی تستها در داخل نحو مستندات، قطعات مستندات را به عنوان کدهای عادی پایتون که در Markdown قرار دارند، در نظر میگیرد. این به طور مؤثر Markdown را به یک کانتینر تست نازک تبدیل میکند و نمایش را از روششناسی تست جدا میسازد.
یک بلوک قابل اجرا در Markdown به این صورت است:
```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
هنگامی که رندر میشود، این بلوک به عنوان یک مثال کد استاندارد ظاهر میشود. با این حال، در طول آزمایش، به عنوان کد پایتون عادی اجرا میشود. این ماهیت دوگانه تضمین میکند که مستندات برای خوانندگان تمیز باقی میمانند، در حالی که مثالهای قوی و قابل آزمایش برای توسعهدهندگان ارائه میدهد. این رویکرد به ویژه برای حوزههای پیچیده مانند هوش مصنوعی، که مثالها اغلب شامل مراحل پیچیده بارگذاری مدل و استنتاج هستند، تأثیرگذار است.
## یکپارچگی یکپارچه با `pytest` و ویژگیهای پیشرفته
یکی از عوامل تمایز اصلی رویکرد Hugging Face، یکپارچگی یکپارچه آن با فریمورکهای تست مدرن، به ویژه `pytest` است. با نصب `hf-doc-builder`، `pytest` میتواند بلوکهای قابل اجرا را در فایلهای Markdown به طور خودکار کشف و اجرا کند و هر بلوک را به عنوان یک آیتم تست استاندارد در نظر بگیرد. این بدان معناست که مثالهای مستندات میتوانند به طور کامل در زیرساخت تست موجود یک پروژه شرکت کنند و از ویژگیهای قدرتمند `pytest` مانند Assertionها، Fixtureها، ابزارهای اشکالزدایی و گزارشدهی جامع بهرهبرداری کنند.
### تکامل مستندات اجرایی: `doctest` در مقابل `doc-builder`
| ویژگی | `doctest` (سنتی) | `doc-builder` (مارکداون قابل اجرای مدرن) |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **رویکرد تست** | تستها را به عنوان جلسات مفسر در مستندات جاسازی میکند | قطعات مستندات را به عنوان کد پایتون عادی برای تست در نظر میگیرد |
| **یکپارچهسازی** | ماژول کتابخانه استاندارد | پلاگین `pytest` برای یکپارچهسازی یکپارچه |
| **نحو تست** | پرامپتهای `>>>`، تطبیق خروجی مورد انتظار | کد استاندارد پایتون، Assertionهای `pytest` |
| **انعطافپذیری** | محدود، تطبیق خروجی شکننده | بالا، از تستهای پیچیده، Decoratorها، اشکالزدایی پشتیبانی میکند |
| **تمیزی مستندات**| میتواند مستندات را با مکانیزمهای تست شلوغ کند | مستندات تمیز را با دستورالعملهای پنهان حفظ میکند |
| **اشکالزدایی** | مقایسه رشته، بازرسی کمتر مستقیم | اشکالزدایی استاندارد پایتون، Tracebackهای کامل |
| **راهاندازی/پایاندهی** | میتواند به مثالها نویز اضافه کند | زمینه را به طور مؤثر با بلوکهای ادامه مدیریت میکند |
| **منبع حقیقت** | قالب مستندات و تستهای جاسازی شده | منبع Markdown، تست شده از طریق اجرای استاندارد پایتون |
`doc-builder` همچنین **بلوکهای ادامه** را معرفی میکند، یک ویژگی حیاتی برای آموزشهای چند مرحلهای. این بلوکها به نویسندگان امکان میدهند تا یک مثال را در چندین قطعه قابل مشاهده تقسیم کنند، مانند `runnable:test_basic` و سپس `runnable:test_basic:2`. نکته مهم این است که این بلوکها در طول تستها یک زمینه اجرای مشترک دارند و یک جریان آموزشی طبیعی را بدون اجبار به قرار دادن تمام کد در یک بلوک طولانی امکانپذیر میسازند. این انعطافپذیری برای راهنمایی کاربران در استفاده پیچیده از مدلهای هوش مصنوعی یا خطوط لوله پردازش داده حیاتی است.
به عنوان مثال، یک گردش کار توسعه عامل هوش مصنوعی میتواند شامل چندین مرحله باشد: تعریف ابزارهای عامل، مقداردهی اولیه عامل، و سپس اجرای یک پرس و جو. بلوکهای ادامه به هر یک از این مراحل اجازه میدهند تا به وضوح در بخشهای مستندات جداگانه ارائه شوند، در حالی که به عنوان یک توالی تست واحد و منسجم اجرا میشوند، مشابه اینکه چگونه گردشهای کاری عاملی پیشرفته [عملیاتیسازی هوش مصنوعی عاملی: بخش ۱](/fa/operationalizing-agentic-ai-part-1-a-stakeholders-guide) هستند.
## حفظ مستندات تمیز در عین اطمینان از تست قوی
یکی از ظریفترین راهحلهای `doc-builder`، توانایی آن در تمیز نگه داشتن مستندات رندر شده است، حتی زمانی که Markdown منبع حاوی دستورالعملهای خاص تست باشد. توسعهدهندگان میتوانند کامنتهایی مانند `# doc-builder: hide` را برای خطوط اجرایی که نباید در مستندات ظاهر شوند، یا `# doc-builder: ignore-bare-assert` را برای Assertionهایی که بخشی از تست هستند اما کامنت آنها نباید رندر شود، جاسازی کنند. به همین ترتیب، Decoratorهای `pytest` (`# pytest-decorator: ...`) در هنگام رندر حذف میشوند.
این امر تضمین میکند که مستندات بر آموزش و وضوح متمرکز باقی میمانند، بدون اینکه با کدهای تکراری (boilerplate) تست شلوغ شوند. کاربر فقط کد مربوطه را میبیند، در حالی که سیستم زیرین عملکرد آن را تضمین میکند. این تعادل برای مستندات ابزارهای توسعهدهنده، جایی که هم جذابیت بصری و هم صحت مطلق از اهمیت بالایی برخوردارند، حیاتی است.
## تأثیر بر پروژههای هوش مصنوعی در مقیاس بزرگ و فراتر از آن
برای مخازن عظیم مانند Transformers از Hugging Face، با صدها صفحه مستندات و هزاران مثال، این ویژگی تحولآفرین است. این امر از 'عدم همگامی مستندات' به طور خودکار جلوگیری میکند، مشکلی که در غیر این صورت به تلاش دستی فراوان نیاز داشت یا منجر به جریان ثابتی از مثالهای شکسته میشد. مستندات قابل اجرا به همگام نگه داشتن مستندات و پایگاه کد کمک میکند و قابلیت اطمینان را در مقیاسی که بازبینی دستی به سادگی غیرممکن است، حفظ میکند. این امر با تلاشهای گستردهتر در جامعه هوش مصنوعی برای [ارزیابی عوامل هوش مصنوعی برای تولید](/fa/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.
بهروز بمانید
آخرین اخبار هوش مصنوعی را در ایمیل خود دریافت کنید.