How do I include the homepage in the Sphinx TOC?

Question

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.

Answer 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