当渲染时，这个块会显示为标准的代码示例。然而，在测试期间，它会作为普通的 Python 代码执行。这种双重性质确保了文档对读者保持整洁，同时为开发者提供了健壮、可测试的示例。这种方法对于 AI 等复杂领域尤其有效，因为其中的示例通常涉及复杂的模型加载和推理步骤。
## 与 `pytest` 和高级功能的无缝集成
Hugging Face 方法的一个关键区别在于它与现代测试框架，特别是 `pytest` 的无缝集成。安装 `hf-doc-builder` 后，`pytest` 可以自动发现并执行 Markdown 文件中的可运行块，将每个块视为一个标准的测试项。这意味着文档示例可以充分参与项目现有的测试基础设施，利用 `pytest` 强大的功能，如断言、fixture、调试工具和全面的报告。
### 可执行文档的演变：`doctest` 与 `doc-builder`
| 特性 | `doctest`（传统） | `doc-builder`（现代可运行 Markdown） |
| :--------------------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| **测试方法** | 将测试作为解释器会话嵌入到文档中 | 将文档片段视为普通的 Python 代码进行测试 |
| **集成** | 标准库模块 | `pytest` 插件实现无缝集成 |
| **测试语法** | `>>>` 提示符，预期输出匹配 | 标准 Python 代码，`pytest` 断言 |
| **灵活性** | 有限，脆弱的输出匹配 | 高，支持复杂测试、装饰器、调试 |
| **文档整洁度** | 可能会用测试机制弄乱文档 | 通过隐藏指令保持文档整洁 |
| **调试** | 字符串比较，直接检查较少 | 标准 Python 调试，完整回溯 |
| **设置/拆卸** | 可能会给示例增加噪音 | 通过延续块有效管理上下文 |
| **事实来源** | 文档格式和嵌入式测试 | Markdown 源文件，通过标准 Python 执行进行测试 |
`doc-builder` 还引入了**延续块**，这是多步骤教程的一个关键功能。它们允许作者将一个示例分割成多个可见的代码片段，例如 `runnable:test_basic` 后面跟着 `runnable:test_basic:2`。重要的是，这些块在测试期间共享相同的执行上下文，从而实现了自然的教学流程，而无需将所有代码强制放入一个长块中。这种灵活性对于指导用户完成复杂的 AI 模型使用或数据处理管道至关重要。
例如，一个 AI 智能体开发工作流可能涉及多个步骤：定义智能体的工具、初始化智能体，然后运行查询。延续块允许将这些步骤分别清晰地呈现在不同的文档部分中，同时作为一个单一、连贯的测试序列执行，类似于高级智能体工作流的 [AI 智能体运营：第一部分](/zh/operationalizing-agentic-ai-part-1-a-stakeholders-guide)。
## 在确保健壮测试的同时保持文档整洁
`doc-builder` 最优雅的解决方案之一是它能够保持渲染后的文档整洁，即使源 Markdown 包含测试特定的指令。开发者可以嵌入诸如 `# doc-builder: hide` 的注释，用于那些应该可执行但不在文档中显示的行；或者 `# doc-builder: ignore-bare-assert`，用于作为测试一部分但其注释不应被渲染的断言。同样，`pytest` 装饰器（`# pytest-decorator: ...`）在渲染时也会被剥离。
这确保了文档仍然专注于教学和清晰度，而不会被测试样板代码所混淆。用户只会看到相关的代码，而底层系统则保证其功能性。这种平衡对于开发者工具的文档至关重要，因为美观性和绝对正确性都极其重要。
## 对大型 AI 项目及其他领域的影响
对于像 Hugging Face 的 Transformers 这样拥有数百个文档页面和数千个示例的庞大代码库，此功能具有变革性意义。它自动化地防止了文档漂移，否则这将需要巨大的手动工作量，或者导致源源不断的失效示例。可运行文档有助于保持文档和代码库同步，在大规模情况下手动审查根本不可行时，维护其可信度。这与 AI 社区为严格 [评估用于生产的 AI 智能体](/zh/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals) 和确保可靠性所做的广泛努力相符。
通过将可执行文档带入 `pytest` 和复杂 CI/CD 管道的现代时代，Hugging Face 展示了对开发者体验和代码质量的强大承诺。其目标与二十多年前一样：文档示例应该能够工作。但现在，它们不仅说明代码*应该*如何工作，而且持续*证明*它确实有效，从而为 AI 开发培养了一个更可靠、更值得信赖的生态系统。
常见问题
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新闻发送到您的收件箱。