Markdown yang Dapat Dijalankan: Merevolusi Pengujian Dokumentasi dengan Hugging Face

Dokumentasi berfungsi sebagai jembatan penting antara pengembang dan alat mereka, tetapi keandalannya sering kali terganggu oleh masalah yang meresap: documentation drift. Seiring perkembangan perangkat lunak, contoh kode dalam dokumentasi dapat rusak secara diam-diam, menyebabkan frustrasi, waktu yang terbuang, dan terkikisnya kepercayaan. Hugging Face, pemimpin dalam inovasi AI, mengatasi tantangan ini secara langsung dengan proyek doc-builder-nya, memperkenalkan blok Markdown yang dapat dijalankan yang memastikan contoh dokumentasi tidak hanya bersifat ilustratif, tetapi juga diuji secara ketat. Pendekatan modern ini mendefinisikan ulang cara kita mendekati dokumentasi yang dapat dieksekusi, menggabungkan kejelasan dokumen yang baik dengan ketahanan pengujian berkelanjutan.

Tantangan: Menjembatani Dokumentasi dan Integritas Kode

Filosofi inti di balik dokumentasi yang dapat dijalankan bukanlah hal baru. Selama puluhan tahun, komunitas Python telah menganjurkan contoh dalam dokumentasi yang dapat disalin, ditempel, dan diharapkan berjalan dengan sempurna oleh pengguna. Namun, mempertahankan cita-cita ini di seluruh proyek besar yang berkembang pesat seperti pustaka Transformers milik Hugging Face adalah tugas yang monumental. Verifikasi manual tidak praktis, dan metode tradisional sering kali memaksa kompromi antara dokumentasi yang jelas dan pengujian yang efektif.

Masalah muncul dari perbedaan mendasar dalam persyaratan:

Contoh dokumentasi memprioritaskan keringkasan, keterbacaan, dan fokus pada pengajaran. Tujuannya adalah bebas dari "noise."
Tes menuntut pernyataan (assertions), setup/teardown, fixture, mocking, dan kemampuan debugging. Tujuannya memprioritaskan ketahanan dan cakupan.

Ketika kedua perhatian ini dipaksakan ke dalam format yang sama, salah satunya sering menderita. doc-builder Hugging Face bertujuan untuk menyelesaikan ketegangan ini dengan memungkinkan dokumentasi tetap bersih sementara contoh-contoh yang mendasarinya divalidasi secara ketat, memastikan bahwa setiap cuplikan yang ditemui pengguna adalah kebenaran yang dapat diverifikasi, bukan hanya sebuah aspirasi. Ini sangat penting untuk menjaga kredibilitas dan mempercepat adopsi pengembang di dunia AI yang bergerak cepat.

Warisan `doctest`: Inovasi Awal dan Kebutuhan yang Berkembang

Konsep dokumentasi yang dapat dieksekusi mendapatkan daya tarik awal di Python dengan diperkenalkannya doctest di Python 2.1 (2001). Dibuat oleh Tim Peters, doctest adalah solusi yang elegan: ia mengurai contoh dokumentasi yang diformat seperti sesi interpreter Python interaktif (>>> add(2, 3)\n5) dan memverifikasi bahwa output sesuai dengan harapan. Inovasi ini mengubah contoh dokumentasi menjadi tes regresi otomatis, sebuah lompatan signifikan ke depan untuk kualitas kode.

doctest sangat cocok untuk Python, bahasa yang mendorong eksplorasi interaktif. Untuk proyek kecil dan API yang sederhana, ia bekerja sangat baik, menyediakan mekanisme yang sederhana namun kuat untuk memastikan contoh dasar tetap fungsional. Ia mewujudkan semangat "tunjukkan, jangan hanya ceritakan" dalam pengembangan perangkat lunak, menjadikan dokumentasi bagian aktif dari suite pengujian.

Solusi Modern Hugging Face: Blok Markdown yang Dapat Dijalankan

Mengakui keterbatasan pendekatan lama untuk proyek skala besar dan kompleks, proyek doc-builder Hugging Face memperkenalkan pendekatan canggih untuk dokumentasi yang dapat dijalankan. Alih-alih menyematkan tes di dalam sintaks dokumentasi, ia memperlakukan cuplikan dokumentasi sebagai kode Python biasa yang berada di dalam Markdown. Ini secara efektif mengubah Markdown menjadi wadah tes yang tipis, memisahkan presentasi dari metodologi pengujian.

Blok yang dapat dijalankan di Markdown terlihat seperti ini:

```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
```

Ketika dirender, blok ini muncul sebagai contoh kode standar. Namun, selama pengujian, ia dieksekusi sebagai kode Python normal. Sifat ganda ini memastikan bahwa dokumentasi tetap bersih untuk pembaca sambil menyediakan contoh yang kuat dan dapat diuji untuk pengembang. Pendekatan ini sangat berdampak untuk domain yang rumit seperti AI, di mana contoh sering kali melibatkan pemuatan model dan langkah-langkah inferensi yang kompleks.

Integrasi Mulus dengan `pytest` dan Fitur Canggih

Pembeda utama pendekatan Hugging Face adalah integrasi mulusnya dengan kerangka kerja pengujian modern, terutama pytest. Dengan hf-doc-builder terinstal, pytest dapat secara otomatis menemukan dan mengeksekusi blok yang dapat dijalankan di dalam file Markdown, memperlakukan setiap blok sebagai item tes standar. Ini berarti contoh dokumentasi dapat sepenuhnya berpartisipasi dalam infrastruktur pengujian proyek yang sudah ada, memanfaatkan fitur-fitur canggih pytest seperti pernyataan (assertions), fixture, alat debugging, dan pelaporan komprehensif.

Evolusi Dokumentasi yang Dapat Dieksekusi: `doctest` vs. `doc-builder`

Fitur	`doctest` (Tradisional)	`doc-builder` (Markdown yang Dapat Dijalankan Modern)
Pendekatan Pengujian	Menyematkan tes sebagai sesi interpreter di dokumen	Memperlakukan cuplikan dokumen sebagai kode Python normal untuk pengujian
Integrasi	Modul pustaka standar	Plugin `pytest` untuk integrasi tanpa batas
Sintaks Tes	`>>>` prompt, pencocokan output yang diharapkan	Kode Python standar, pernyataan `pytest`
Fleksibilitas	Terbatas, pencocokan output yang rapuh	Tinggi, mendukung tes kompleks, decorator, debugging
Kebersihan Dokumentasi	Dapat mengotori dokumen dengan mekanisme tes	Mempertahankan dokumen bersih dengan direktif tersembunyi
Debugging	Perbandingan string, inspeksi yang kurang langsung	Debugging Python standar, traceback lengkap
Setup/Teardown	Dapat menambah "noise" pada contoh	Mengelola konteks secara efektif dengan blok kelanjutan
Sumber Kebenaran	Format dokumentasi dan tes yang disematkan	Sumber Markdown, diuji melalui eksekusi Python standar

doc-builder juga memperkenalkan blok kelanjutan, fitur krusial untuk tutorial multi-langkah. Ini memungkinkan penulis untuk membagi contoh di beberapa cuplikan yang terlihat, seperti runnable:test_basic diikuti oleh runnable:test_basic:2. Yang krusial, blok-blok ini berbagi konteks eksekusi yang sama selama pengujian, memungkinkan alur instruksional alami tanpa memaksa semua kode ke dalam satu blok panjang. Fleksibilitas ini sangat penting untuk memandu pengguna melalui penggunaan model AI kompleks atau pipeline pemrosesan data.

Misalnya, alur kerja pengembangan agen AI dapat melibatkan beberapa langkah: mendefinisikan alat agen, menginisialisasi agen, dan kemudian menjalankan kueri. Blok kelanjutan memungkinkan setiap langkah ini disajikan dengan jelas di bagian dokumentasi terpisah sambil dieksekusi sebagai urutan tes tunggal yang kohesif, mirip dengan bagaimana alur kerja agentic tingkat lanjut Mengoperasionalisasikan AI Agen: Bagian 1.

Menjaga Dokumentasi Tetap Bersih Sambil Memastikan Pengujian yang Kuat

Salah satu solusi paling elegan dari doc-builder adalah kemampuannya untuk menjaga dokumentasi yang dirender tetap bersih, bahkan ketika sumber Markdown berisi direktif khusus pengujian. Pengembang dapat menyematkan komentar seperti # doc-builder: hide untuk baris yang dapat dieksekusi tetapi tidak boleh muncul dalam dokumentasi, atau # doc-builder: ignore-bare-assert untuk pernyataan yang merupakan bagian dari tes tetapi komentarnya tidak boleh dirender. Demikian pula, decorator pytest (# pytest-decorator: ...) dihilangkan selama rendering.

Ini memastikan bahwa dokumentasi tetap fokus pada pengajaran dan kejelasan, tanpa diotori oleh boilerplate pengujian. Pengguna hanya melihat kode yang relevan, sementara sistem yang mendasarinya menjamin fungsinya. Keseimbangan ini sangat penting untuk dokumentasi alat pengembang, di mana daya tarik estetika dan kebenaran mutlak sangat penting.

Dampak pada Proyek AI Skala Besar dan Lebih Luas

Untuk repositori besar seperti Transformers milik Hugging Face, dengan ratusan halaman dokumentasi dan ribuan contoh, fitur ini bersifat transformatif. Ini mengotomatiskan pencegahan dokumentasi drift, masalah yang jika tidak akan membutuhkan upaya manual yang sangat besar atau menyebabkan aliran konstan contoh yang rusak. Dokumentasi yang dapat dijalankan membantu menjaga dokumentasi dan codebase tetap sinkron, mempertahankan kepercayaan pada skala di mana tinjauan manual tidak praktis. Ini sejalan dengan upaya yang lebih luas dalam komunitas AI untuk secara ketat Mengevaluasi Agen AI untuk Produksi dan memastikan keandalan.

Dengan membawa dokumentasi yang dapat dieksekusi ke era modern pytest dan pipeline CI/CD yang canggih, Hugging Face menunjukkan komitmen yang kuat terhadap pengalaman pengembang dan kualitas kode. Tujuannya tetap sama seperti dua dekade lalu: contoh dokumentasi harus berfungsi. Tetapi sekarang, mereka tidak hanya mengilustrasikan bagaimana kode seharusnya berfungsi tetapi terus-menerus membuktikan bahwa itu berfungsi, mendorong ekosistem yang lebih andal dan dapat dipercaya untuk pengembangan AI.

Sumber asli

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

Pertanyaan yang Sering Diajukan

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.

Tetap Update

Dapatkan berita AI terbaru di inbox Anda.