使用阅读文档主题时如何将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文档就不会给你足够的信息.简而言之,您必须覆盖模板:

• 确保_templatessphinx docs文件夹下有一个文件夹.
• 确保它列在您的中conf.py,例如 templates_path = ['_templates']
• 在名为的文件夹中创建一个文件layout.html.

• 把这个片段放在里面然后保存.感叹号/标记迫使jinja使用父模板.不要忘记它,否则你会得到一个递归错误.您只需要覆盖该menu块.

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