CODEWITHSUNDEEP
python-sphinxsidebartableofcontents
Tom Grundy
Tom Grundy

Reputation: 826

Sphinx sidebar table of contents: include section headers

I'm using the Alabaster theme in Sphinx. The sidebar is set to show a local table of contents and a few other things. From conf.py:

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

On the page that documents class methods, sartopo_python.rst, I manually categorized the methods, and added section headers to show the start of each category of methods:

:tocdepth: 3

sartopo\_python module
======================
.. see https://stackoverflow.com/a/48682589/3577105
.. currentmodule:: sartopo_python

.. autoclass:: SartopoSession

   **Session setup methods**
   -------------------------

   .. automethod:: openMap
   .. automethod:: _setupSession
   .. automethod:: _sendUserdata

   **Account data access methods (may be called from a mapless session)**
   ----------------------------------------------------------------------

   .. automethod:: getAccountData
   .. automethod:: getMapList

... and so on...

These section headers render as expected in the main frame.

However - the sidebar table of contents only shows the methods - it doesn't show the categories / the custom headers.

enter image description here

I'd really also like these custom headings (the 'categories') to show up in the sidebar table of contents. What's the way to accomplish this?

Some comments at this question hint that the table of contents is only designed to show (nested) HTML lists - so maybe the solution lies in actually making the category headings into a level of the lists of methods? If so, how can that be accomplished?

Upvotes: 0

Views: 260

Answers (1)

Tom Grundy
Tom Grundy

Reputation: 826

Stumbled upon a solution:

enter image description here

The changes to sartopo_python.rst:

  • unindent headings - but this doesn't work on its own, see inline comments
  • add the module name to each automethod directive

After making those changes, the automethod lines work fine if unindented as well, but the indent gives a nice visual indent when rendered.

Here's the same section of the modified sartopo_python.rst:

:tocdepth: 3

sartopo\_python module
======================
.. see https://stackoverflow.com/a/48682589/3577105 for categorization technique
.. currentmodule:: sartopo_python

.. autoclass:: SartopoSession

.. omitting class name from automethod calls, when the section headers are unindented,
..   causes these failures, but, the headers need to be unindented for the TOC to recognize them:
.. WARNING: don't know which module to import for autodocumenting 'openMap' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

**Session setup methods**
-------------------------

   .. automethod:: SartopoSession.openMap
   .. automethod:: SartopoSession._setupSession
   .. automethod:: SartopoSession._sendUserdata

**Account data access methods (may be called from a mapless session)**
----------------------------------------------------------------------

   .. automethod:: SartopoSession.getAccountData
   .. automethod:: SartopoSession.getMapList

... and so on...

One undesirable side effect, but a pretty minor one that may be just fine, is that the rendered page has the module name at the start of every method. It takes up a bit more space, but might actually be a benefit for clarity.

One bit of icing on the cake would be the ability to collapse all sections/categories of the sidebar toc, except for the one that is currently being viewed. But - it's probably good enough to move forward as-is.

It's possible that this isn't actually the intended behavior of sphinx or of the alabaster theme, but, that's OK!

Upvotes: 0

Related Questions