12

When inserting a document in a toctree, the link displayed is the main title of the document. So when I do:

.. toctree::
   materials/diffuse
   materials/glossy
   materials/specular

I get:

Materials

  • Diffuse material
  • Glossy material
  • Specular material

The word "material" is clearly redundant in the toctree, but is important in the document titles for good understanding.

RST allows me to write this:

.. toctree::
   Diffuse<materials/diffuse>
   Glossy<materials/glossy>
   Specular<materials/specular>

But I do not like this, as renaming a document requires updating the index toctree, and link updating is why I went from MediaWiki to Sphinx. Also, this disables the use of :glob: and wildcards in the toctree

Question: Is there any way to specify a toctree title in the leaf document itself, for instance in "diffuse.rst", as a meta-property?

Thanks!

bad_coder
  • 11,289
  • 20
  • 44
  • 72
galinette
  • 8,896
  • 2
  • 36
  • 87

1 Answers1

1

In concept, the css content property would be applicable here. Assuming your title is rendered with <h1> element, you'd want something like this:

.. raw:: html

   <style>
      h1:after {
         content: " Material";
      }
   </style>

The <style>...</style> block is doing the work. Your docs keep the one word titles (Diffuse, Glossy, Specular) and the css adds " Material" on render. So your pages have the title you want, and your toctree doesn't have the redundant "Material" for each item. However, you'd want that block to appear only on the pages in your "Materials" section -- you can't just add it to the main css file, or it will affect all <h1> elements. Unfortunately, Sphinx doesn't have a mechanism for properly creating a <style> block in a page's <head> section, as far as I know. Therefore to use this css technique you have to accept the complete hack of dropping it in a .. raw:: html directive as shown, somewhere on your page. It won't really matter where you put it in your doc -- any location you choose will produce non-valid html, but will render what you want: your toctree labels will not contain "material"; your page titles will.

csinmpls
  • 21
  • 2