Call contents from docutils instead of toc in localtoc.html?

[Boris Kheyfets]

{{ toc }} in localtoc.html includes headings of first level. I have only one such heading per .rst file — the title of the page. And I don't want local toc to include it. The desired functionality is provided by the contents of the docutils:

.. contents::
   :local:
   :depth: 1
   :backlinks: none

I'd like to call it instead of toc in localtoc.html. Here'a subclass I need:

from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.parts import Contents

class localtoc(Contents):
    option_spec = {'depth': 2,
                   'local': True,
                   'backlinks': None,
                   'class': directives.class_option}
    def run(self):
        rst = super(Contents, self).run()
        return rst

But how do I call it from jinja during the sphinx build?

[Takayuki Shimizukawa]

Hi Boris,

If you want to pass some variables/functions to jinja2 template,
``html_context`` conf.py setting will help you.
However, the ``localtoc`` class is a directive that only works with reST source.

So, I made a little extension to render headings in the page exclude a
page title.
https://gist.github.com/shimizukawa/8300704
Please try it.

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

[Boris Kheyfets]

Thank You Takayuki,

it works: I put it into $SPHINX/ext and added as sphinx.ext.localtoc.

However for my current project I'm already using localtoc.html with just {{ toc }} and custom post-processing afterwards (I've patched sphinx to be explicit about what html pages are new, changed or deleted — so not to patch all pages all the time). It works fine and I'm struggling with css features I wanted.

Thank You again, for Your effort.

_____

Boris

--
You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/d0dwJ4YiMhs/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sphinx-users...@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

[Boris Kheyfets]

Dear Takayuki SHIMIZUKAWA,

I'm re-making my basic sphinx template. And now I'm using your snippet. Thank you so much. The only modification I made is removing <ul><li> which wrap the localtoc:

# -*- coding: utf-8 -*-
"""
``localtoc``: A callable yielding the local TOC tree that contains
list of all headings in the specified page exclude page title.
``localtoc`` need pagename specifing like ``{{ localtoc(pagename) }}``.
"""

def init_localtoc(app):

    def _get_localtoc(docname):
        toc = app.env.get_toc_for(docname, app.builder)
        try:
            del toc[0][0]
            return app.builder.render_partial(toc)['fragment'][9:-12] # HERE
        except:
            return ''

    ctx = app.env.config['html_context']
    if 'localtoc' not in ctx:
        ctx['localtoc'] = _get_localtoc


def setup(app):
    app.connect('builder-inited', init_localtoc)

I grow tired of post-processing sphinx generated htmls, and you solution solves the issue wonderfully.