从 Sphinx 文档中删除“模块”一词答案

【问题标题】：Remove the word "module" from Sphinx documentation从 Sphinx 文档中删除“模块”一词
【发布时间】：2018-05-16 01:27:44
【问题描述】：

使用Sphinx 记录我的 Python 项目。我想删除每个 python 文件（在导航栏、TOC、页面标题等中）名称后面的“模块”一词。

例如详情：

项目由utils.py和main.py两个文件组成。

在我的index.rst 文件中，我使用：

.. toctree::
   :maxdepth: 2

   utils
   main

将两个文件作为“模块”导入。然后我从docs/ 文件夹中调用：

sphinx-apidoc -f -o ./source/ .. 
make html

生成静态站点。在站点中，每个文件名后面都有“模块”一词，我想将其删除。

【问题讨论】：

在sphinx-apidoc -f -o ./source/ .. 之后，你的utils.rst 和main.rst 是什么？我认为部分问题在于sphinx-apidoc is designed for packages，而不是模块：“sphinx-apidoc 是一种用于自动生成 Sphinx 源的工具，它使用 autodoc 扩展，以如下方式记录整个包其他自动 API 文档工具。”
stackoverflow.com/q/29385564/407651的可能重复

标签： python python-sphinx

【解决方案1】：

Sphinx 2.2 为 sphinx-apidoc 生成的 reST 文件添加了模板。

使用--templatedir 选项将路径设置为包含module.rst_t、package.rst_t 和toc.rst_t 文件的目录。可以从site-packages/sphinx/templates/apidoc中的对应文件创建文件。

然后，在package.rst_treplace

{{- [submodule, "module"] | join(" ") | e | heading(2) }}

与

{{- submodule | e | heading(2) }}

重复module.rst_t。

【讨论】：

根据sphinx-doc.org/en/master/changes.html#id9，--templatedir 选项已在 Sphinx 2.2.0 中添加。
@mzjn 是的，但据我所知，该版本尚未发布（无法通过 PyPI / pip 获得）。
奇怪的是它不适合你。我能够通过 pip 安装它。 pypi.org/project/Sphinx 说 2.2.0 是最新版本。
啊——它是 8 月 18 日发布的。我在 16 号发布了这个答案 :)
我在我的电脑上找不到site-packages/sphinx/templates/apidoc的默认文件，但你可以找到它们here

【解决方案2】：

一种可能的解决方案是使用 JS 在页面加载后查找和替换“模块”一词：

创建一个文件source/_templates/layout.html，内容如下：

{% extends "!layout.html" %}
{% block extrahead %}
<script type="text/javascript">
  window.onload = function() {
    document.body.innerHTML = document.body.innerHTML.replace(/ module/g, '');
  }
</script>
{% endblock %}

确保conf.py 设置了templates_path = ['_templates']，然后Sphinx 会将脚本附加到所有文档页面的<head>，瞧！

【讨论】：