Font styling when annotating Sphinx toctree

192 views Asked by At

I'm trying to build documentation for a Python project using Sphinx (using autodoc with the readthedocs theme). I want to override the text in the table of contents side bar. Following this example, I can achieve this by modifying the toctree in index.rst

.. toctree::
   :maxdepth: 2

   This is an annotation <thisisthenameoftherstfile>

In the table of contents side-bar in HTML, this now renders as

This is an annotation 

rather than

thisisthenameoftherstfile

So far so good; Sadly, I can't seem to style text this way. For example

.. toctree::
   :maxdepth: 2

   **modulename**: *Routines for thing* <thisisthenameoftherstfile>
   <b>modulename</b>: <i>Routines for thing<i> <thisisthenameoftherstfile>

Renders in the HTML, sadly, as

   **modulename**: *Routines for thing*
   <b>modulename</b>: <i>Routines for thing</i>

I'm a little surprised that <b></b> etc render verbatim, as I thought you could only do this using the <pre> tag. I've tried inspecting the CSS in the browser and I can't figure out what property is causing these tags to be ignored / rendered as text rather than interpreted as text styling. Evidently markdown styling isn't interpreted either.

Is there any way to fix this? I'd like to see things like

  • Module named_module: I do this thing

In the side bar, where the content of the annotation text is bespoke to each table-of-contents entry, and defined entirely at the top-level index.rst file only (so, not part of the information in the lower-level .rst files i.e. thisisthenameoftherstfile.rst in this example.)

0

There are 0 answers