如何在Rustdoc中添加非Rust源文件？

这里有几种实用方案可以把你的Pest语法文件整合到rustdoc生成的文档里：

• 直接嵌入到Rust源码的文档注释中
  用include_str!宏把Pest文件内容导入到模块或库的文档注释里，再用代码块标记语法：

  //! # 项目的Pest语法定义
  //! 以下是核心的语法规则：
  //! ```pest
  #[doc = include_str!("../grammar.pest")]
  //! ```
  

  这样rustdoc会把Pest文件的内容渲染成带语法高亮的代码块，和其他Rust文档放在一起。

• 创建自定义Markdown文档页面
  在项目的src/doc目录下新建一个markdown文件（比如pest_grammar.md），把Pest语法内容用```pest代码块包裹进去。然后在lib.rs的根文档注释里添加指向这个页面的链接：

  //! 查看[Pest语法定义](pest_grammar.md)了解详细规则
  

  构建文档时，rustdoc会自动处理这个md文件，生成对应的HTML页面，用户可以通过链接跳转查看。

• 利用Cargo配置确保文件被包含
  如果你的Pest文件不在默认的构建路径里，需要在Cargo.toml的package.metadata.docs.rs里指定额外的文件，确保构建文档时能访问到：

  [package.metadata.docs.rs]
  extra-files = ["grammar.pest"]
  

  这个配置主要是配合include_str!使用，避免文档构建时找不到Pest文件。

内容的提问来源于stack exchange，提问作者Dekakaruk