CODEWITHSUNDEEP
pythonpython-sphinxsidebartableofcontents
Samufi
Samufi

Reputation: 2710

Sphinx: customize sidebar section titles

I am documenting my Python project with Sphinx. As some of my documentation pages are rather long, I would like to have both a local and a global table of contents in the sidebar. I achieve achieve this via

html_sidebars = { '**': ['localtoc.html', 'globaltoc.html', 'searchbox.html'] }

The result is almost as desired. However, both the local and the global table of contents have the same title ("Table of Contents"). That is, it looks like

Table of Contents
 - Subheading 1
 - Subheading 2
 - Subheading 3

Table of Contents
 - Subpage 1
 - Subpage 2
 - Subpage 3

This is confusing to the reader.

I have located the file localtoc.html in the sphinx package folder of my Python installation, and adjusting the html to my needs (replacing the title) is simple. However, I would not like to change a Sphinx source file, and building my own theme via a python package seems overkill to me.

Is there any way to replace localtoc.html locally, i.e. for the current project only?

Upvotes: 3

Views: 1945

Answers (1)

wstk
wstk

Reputation: 1270

You can override the behaviour of the localtoc.html template.

Create a _templates folder in your Sphinx root (the same place where your conf.py file is located), and copy localtoc.html from your Sphinx installation to this folder.

You can then modify this file as you wish. Remove this line:

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>

to get rid of the extra heading, or you could replace any of the text, as you wish (for example changing the content of the <a> to Local Contents or whatever you like.

Note that changing the localtoc.html removes the top of the two headings. If this is what you wanted, great! If not, you could replicate the process just using globaltoc.html in the same way.

Upvotes: 3

Related Questions