List functions in table of contents in Sphinx

Question

How can I list functions, classes, etc... to show up in the table of contents in Sphinx?

Or, more generally, how can I add arbitrary entries within a page (not subtitles) to the table of contents?

BTW: I'm not documenting Python code, so I can't use the autodoc tools.

Edit

I tried the directive .. contents:: name, but that seems to be for placing a ToC, not defining an entry.

Edit: Partial Solution

I copied the basic/localtoc.html template to my _templates directory.

{{ pagename }} gives the path to the current file and {% include filename %} lets me include a file, so I could presumably combine those, and just generate my own Table of Contents for every file whenever conf.py is run. I will try this, but is there a more automatic solution?

Answer 1

Instead of creating lots of individual templates, one can create a single template that uses javascript to populate extra entries on the table of contents at load time.

I can use viblo's script from Toc/list with all classes generated by automodule in sphinx docs that dynamically generates lists of Classes, Functions, and Variables.

My _templates/localtoc.html then becomes:

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{%- if display_toc %}

  {{ toc }}
{%- endif %}
<div class="custom-index container">
<script type="text/javascript" src={{ pathto(master_doc)[:-10] + '_static/pymunk.js' }}></script>

</div>

Answer 2

I tend to group members into public and private sections in the API documentation, so I want them to appear inside the TOC hierarchy. I adapted @viblo's and @ramcdougal's solutions to achieve this.

Here's my _static/apitoc.js:

// Inject API members into the TOC in the sidebar.
// This should be loaded in the localtoc.html template.

$(function (){
    $('div.section').each(function(index) {
        var $section = $(this),
            $tocitem = $('.sphinxlocaltoc li:has(> a.reference.internal[href="#' + 
                         $section.attr('id') +
                         '"])');
            $members = $('<ul>').appendTo($tocitem);
        $('> dl > dt', $section).each(function(index) {
            var $member = $(this),
                $tocMember = $('<li class="api-member">');
            $tocMember.text($('.property', $member).text() + ' ');
            $tocMember.append('<a href="#' + $member.attr('id') + '">' + 
                              $('.descname', $member).text() + 
                              '</a>');
            $members.append($tocMember);
        });
    });
});

And here's _templates/localtoc.html:

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{%- if display_toc %}
  {{ toc }}
  <div class="custom-index container">
    <script type="text/javascript" src={{ pathto(master_doc)[:-10] + '_static/apitoc.js' }}></script>
  </div>
{%- endif %}

The result looks like:

---

Page contents

mypackage.mymodule

• Public API
  • class MyPublicClass
  • class AnotherPublicClass
  • my_public_function
• Private API
  • class MyPrivateClass
  • my_private_function