Add classes to toctree items that indicate depth.

CHANGES

@@ -45,6 +45,12 @@ New features added
   - The JavaScript search now searches for objects before searching in
     the full text.
 
+  - TOC tree entries now have CSS classes that make it possible to
+    style them depending on their depth.
+
+  - Highlighted code blocks now have CSS classes that make it possible
+    to style them depending on their language.
+
   - HTML ``<meta>`` tags via the docutils ``meta`` directive are now
     supported.
 

sphinx/environment.py

@@ -902,9 +902,10 @@ class BuildEnvironment:
             """Utility: Cut a TOC at a specified depth."""
             for subnode in node.children[:]:
                 if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
+                    subnode['classes'].append('toctree-l%d' % (depth-1))
                     _walk_depth(subnode, depth, maxdepth, titleoverrides)
                 elif isinstance(subnode, nodes.bullet_list):
-                    if depth > maxdepth:
+                    if maxdepth > 0 and depth > maxdepth:
                         subnode.parent.replace(subnode, [])
                     else:
                         _walk_depth(subnode, depth+1, maxdepth, titleoverrides)
@@ -958,9 +959,8 @@ class BuildEnvironment:
 
         newnode = addnodes.compact_paragraph('', '', *tocentries)
         newnode['toctree'] = True
-        # prune the tree to maxdepth and replace titles
-        if maxdepth > 0 and prune:
-            _walk_depth(newnode, 1, maxdepth, titleoverrides)
+        # prune the tree to maxdepth and replace titles, also set level classes
+        _walk_depth(newnode, 1, prune and maxdepth or 0, titleoverrides)
         # replace titles, if needed, and set the target paths in the
         # toctrees (they are not known at TOC generation time)
         for refnode in newnode.traverse(nodes.reference):

tests/test_build.py

@@ -70,6 +70,8 @@ HTML_XPATH = {
     'contents.html': {
         ".//meta[@name='hc'][@content='hcval']": '',
         ".//td[@class='label']": '[Ref1]',
+        ".//li[@class='toctree-l1']/a": 'Testing various markup',
+        ".//li[@class='toctree-l2']/a": 'Admonitions',
     },
 }