如何在Sphinx中隐藏主页目录的章节标题且保留侧边栏章节导航？

解决方案 #

方案1：调整主页toctree的maxdepth参数（最优解） #

你不需要使用:titlesonly:参数，只需要把主页index.rst里toctree的:maxdepth设为1即可：

.. toctree::
   :maxdepth: 1

   installation
   api
   support

这个参数仅作用于当前页面的toctree指令，只会拉取每个关联文档的一级标题（即每个rst文件的顶部大标题），不会向下抓取二级及以下的子章节，完全满足你主页仅展示单条页面链接的需求。同时该参数不会影响子页面侧边栏的章节导航逻辑，侧边栏的显示规则完全独立。

方案2：单独配置侧边栏展示深度（配合主题使用） #

如果你使用的是主流的sphinx_rtd_theme（Read the Docs主题），还可以在项目的conf.py中单独配置侧边栏的章节展示深度，和主页目录规则完全隔离：

html_theme_options = {
    # 控制侧边栏最多展示3级章节，可根据需求调整数值
    "navigation_depth": 3,
}

调整完成后即可实现预期效果：

• 主页目录仅展示每个页面的单条链接，无冗余子章节
• 进入单个文档页面后，侧边栏仍会完整展示当前页的所有章节导航

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