python-sphinx - 使用“阅读文档”主题时如何将Sphinx生成的索引添加到侧栏？

Question

使用sphinx-rtd-theme时，我想在侧栏中有一个指向自动生成的索引的链接。我尝试将其添加到toctree:

.. toctree::

    first
    second
    Index <:ref:`genindex`>

但这导致

WARNING: toctree contains reference to nonexisting document u':ref:`geinindex`'

从狮身人面像，没有其他效果。

我想我可以简单地在主题 layout.html文件中对索引进行硬编码，但是也许有更好的方法，而不涉及修改标准主题？

TIA有任何提示!

Answer 1

如果您了解Sphinx和Jinja的工作原理，那很容易。不幸的是，如果没有，Sphinx docs on templating不会给您足够的信息。简而言之，您将不得不覆盖模板:

确保您的sphinx docs文件夹下有一个_templates文件夹。

确保它已列在conf.py中，例如templates_path = ['_templates']

在名为layout.html的文件夹内创建一个文件。

将此片段放在其中并保存。
感叹号/标记强制Jinja使用父模板。
不要忘记它，否则您将得到递归错误。
您只需要覆盖menu块。

{% extends "!layout.html" %}

  {% block menu %}
    {{ super() }}
    <a href="genindex.html">Index</a>
  {% endblock %}