如何为文档项目配置全局共享的toctree导航？

要实现所有页面侧边栏导航完全一致，最简洁且易维护的方法是创建一个全局的toctree配置文件，然后在每个页面中引入它，完美避开嵌套和侧边栏不一致的问题。具体步骤如下：

1. 创建全局导航文件 #

新建一个名为_toc.rst的文件（文件名可自定义，加下划线是为了标识它是辅助文件，不会被单独渲染成页面），内容如下：

.. toctree::
    :hidden:
    :caption: Site Navigation  # 可选，给侧边栏导航加个标题

    index
    api

这里的:hidden:参数确保这个文件本身不会出现在导航里（不需要隐藏可去掉），:caption:用来给侧边栏的导航区块加个标题，提升可读性。

2. 在每个页面引入全局导航 #

修改你的index.rst，在内容末尾加入include指令：

Welcome!
========
Welcome to these awesome docs!

.. include:: _toc.rst

同样修改api.rst：

API
===
Here is some API stuff...

.. include:: _toc.rst

为什么这个方法有效？ #

• 所有页面共享同一个toctree定义，侧边栏的导航结构100%一致，不会出现你之前遇到的“不同页面侧边栏不一样”的问题。
• 不会产生嵌套问题：每个页面都是直接渲染这个独立的toctree，而非把一个toctree嵌套在另一个里面。
• 后续维护超方便：如果要添加新页面，只需要在_toc.rst里加一行，所有页面的导航都会自动更新，不用逐个修改每个rst文件。

如果你用的是Read the Docs这类支持全局导航的主题，也可以通过conf.py里的html_sidebars配置来统一侧边栏，但上面的include方法更通用，适配绝大多数Sphinx主题。

内容的提问来源于stack exchange，提问作者Maarten-vd-Sande