Sphinx是Python生态中广泛使用的文档生成工具，其侧边栏的文档树（toctree）默认会展示完整的模块导入路径。当项目包层级较深时，例如myproject.utils.io.handlers，侧边栏会被冗长路径占满，既影响视觉也降低检索效率。本文围绕如何精简这些模块路径展开，给出可落地的配置与代码方案。
理解Sphinx侧边栏路径的来源
Sphinx在构建HTML时，侧边栏通常由主题通过toctree指令或自动生成的API文档（如autodoc扩展）填充。如果使用了sphinx.ext.autodoc配合automodule，文档节点标题默认等于模块的完全限定名。这意味着侧边栏树形结构会原样显示package.subpackage.module这样的字符串。
另一个容易被忽略的点是，部分主题（如sphinx_rtd_theme）提供collapse_nav或collapse_level选项，仅控制折叠行为，并不缩短文字。因此单纯依靠主题配置无法删除路径前缀，必须从文档生成源头或模板渲染层介入。
通过conf.py重映射短名称
一种低风险的做法是在conf.py中使用rst_prolog或自定义回调函数，在读取文档前替换标题中的长路径。例如我们想把myproject.core显示为core，可以在配置中注入替换逻辑。
下面示例展示如何利用app.connect在source-read事件里改写内容，使侧边栏对应的rst标题变短：
# conf.py
def shorten_module_path(app, docname, source):
content = source[0]
# 将长路径替换为短名，影响toctree展示
content = content.replace('myproject.core', 'core')
content = content.replace('myproject.utils', 'utils')
source[0] = content
def setup(app):
app.connect('source-read', shorten_module_path)
这种方法的优势是不动主题模板，对所有页面统一生效。缺点是若模块名出现在代码块内也会被替换，因此需要配合更精准的正则，仅处理标题行（如^myproject开头的RST标题）。
重写toctree模板裁剪前缀
如果使用的主题允许覆盖模板，可以复制原主题的localtoc.html或globaltoc.html，在渲染条目时截断路径。以Sphinx基础主题为例，可以在模板中用Jinja2过滤器处理toctree的条目文本。
示例模板片段如下，将每个条目的第一段路径隐藏：
<!-- 自定义 localtoc.html -->
<div class="localtoc">
<ul>
{% for entry in toctree %}
<li>
<a href="{{ entry.url }}">
{{ entry.title.split('.')[-1] }}
</a>
</li>
{% endfor %}
</ul>
</div>
该方式直接控制显示层，不影响文档系统的交叉引用。但维护成本略高，主题升级时需同步修改模板。此外，entry.title的具体属性名依主题而定，编写前应在原模板中确认变量结构。
借助apidoc工具自动生成短路径
sphinxcontrib.apidoc能在构建前自动扫描包并生成rst文件。我们可以通过定制脚本，在生成rst时指定automodule的member-order与标题重写规则，从源头输出短路径文档。
例如下面脚本在调用apidoc后批量重命名标题：
# gen_docs.py
import os
import sphinxcontrib.apidoc as apidoc
apidoc.main(['-f', '-o', 'docs/api', 'myproject'])
for root, _, files in os.walk('docs/api'):
for f in files:
if f.endswith('.rst'):
path = os.path.join(root, f)
with open(path, 'r', encoding='utf-8') as fh:
text = fh.read()
text = text.replace('myproject.core', 'core')
with open(path, 'w', encoding='utf-8') as fh:
fh.write(text)
这种方案适合持续集成环境，每次构建都得到干净短路径。需要注意替换规则应写入版本库，避免不同机器生成结果不一致。结合上文的模板方案，能在不牺牲导航功能的前提下，让侧边栏更紧凑易读。
不同方案的取舍
若项目规模小、路径统一，conf.py字符串替换最省事；若需要精细控制视觉且主题支持覆盖，模板改写最灵活；自动化构建流程则推荐apidoc脚本。实际中可叠加使用，例如apidoc生成短rst，模板再做兜底裁剪。
最后提醒，修改侧边栏显示不应破坏Sphinx的引用机制。短名称仅作展示，交叉引用仍要用完整路径，否则会出现undefined label警告。理清展示与语义的边界，精简路径才真正安全有效。