如何将RTD手册的搜索结果限定至特定板块？
2026-8-14
实现RTD文档分区域搜索的方案
针对你用Read the Docs（RTD）搭建的两类文档（书籍式章节、代码自动生成文档），可以通过以下几种现有机制实现分区域搜索，满足用户用关键词/限定符筛选的需求：
1. 利用目录路径限定搜索（最简便）
RTD基于Sphinx构建，其内置搜索支持通过path:语法限定文档路径。你只需要提前将两类文档放在独立的子目录中：
- 将书籍式章节放在根目录下的
docs/或guide/文件夹 - 将自动生成的代码文档放在
script-reference/或api/文件夹（参考你提到的文档结构）
使用方式：
- 仅搜索自动生成文档：在搜索框输入
path:script-reference/ 你的关键词 - 仅搜索书籍式章节：在搜索框输入
-path:script-reference/ 你的关键词（用-排除自动生成目录的内容）
配置提示：
在文档首页或搜索入口旁添加简短说明，告诉用户这些路径限定符的用法，降低学习成本。
2. 给文档添加自定义标签（更灵活）
通过Sphinx的标签系统，给两类文档打上不同的标签，让用户可以用tag:语法筛选搜索结果：
配置步骤：
- 在Sphinx的
conf.py中启用sphinxcontrib.tags扩展（需先安装sphinxcontrib-tags包） - 给书籍式章节的每个文档添加元数据：
:tags: guide - 给自动生成的代码文档添加元数据：
:tags: api（如果是自动生成的文档，可以在生成脚本中批量添加标签）
使用方式：
- 仅搜索书籍式章节：
tag:guide 你的关键词 - 仅搜索自动生成文档：
tag:api 你的关键词
3. 拆分文档为RTD子项目（备选方案）
如果两类文档独立性很强，可以将自动生成的文档单独作为RTD的子项目，主项目保留书籍式章节。用户可以通过切换RTD页面顶部的「子项目」下拉菜单，在不同项目的搜索框中分别搜索。这种方式不需要用户记忆限定符，但需要维护两个RTD项目。
内容的提问来源于stack exchange，提问作者Christian
相关产品推荐
相关产品推荐
