How do I include the homepage in the Sphinx TOC?

问题

Let’s say I’ve got a Sphinx project with the following sources:

index.rst
installation.rst
templating/
    index.rst
    module.rst
    fieldtype.rst

index.rst (the homepage) has the following TOC tree:

.. toctree::
   :titlesonly:

   installation
   templating/index

I want my template to include a sidebar that lists all 3 top-level pages (homepage, installation, templating/index).

I've tried adding a second, hidden TOC tree in the homepage:

.. toctree::
   :hidden:

   index

.. toctree::
   :titlesonly:

   installation
   templating/index

That actually gives me the desired result, except that it makes the next variable set to the current page. So this code in my template:

Next up: <a href="{{ next.link }}">{{ next.title }}</a>

…always outputs the homepage link from the homepage. No good.

I’ve always tried to hardcode the actual homepage link right into the sidebar of the template:

{% set homeClass = 'current' if pagename == 'index' else '' %}
<ul class="{{ homeClass }}">
    <li class="toctree-l1 {{ homeClass }}"><a class="{{ homeClass }} reference internal" href="/index.html">Home</a></li>
</ul>
{{ toctree() }}

That also works, except that I don’t want to force the docs to be accessed on the webroot of a web server – I want them to work from the file system too.

I can’t simply set the URL to “index.html” because that won’t work when you’re in a file within templating/.

Am I missing something obvious? There must be a way to get the homepage into the TOC, without breaking next links and with a dynamic path that works on a local file system, even from within subfolders.

回答1:

Turns out the answer was hiding in plain sight on Sphinx’s TOC tree page:

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree.

Adding self to the TOC tree did the trick perfectly! And if you place it in a separate, hidden toctree directive, it won’t show up on the homepage’s table of contents either:

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index

回答2:

Is it possible for you to rename your Sphinx project's root toctree page, or, alternatively, the templating/index page? The master_doc variable lets you name the file in your project that contains the root toctree directive, and it doesn't have to be called index.rst... in our documentation project to get around a problem very like this, we have a template/index.html file and our root toctree page is actually called reference.rst.

来源：https://stackoverflow.com/questions/16123951/how-do-i-include-the-homepage-in-the-sphinx-toc

标签

python-sphinx

toctree