readme.rst

Customizing ablog with rtd theme and local toc tree

.. post:: Dec 28, 2018
   :tags: sphinx
   :category: 文档

Screenshots after the customization

The local toc tree in the side bar:

The Ablog features in the side bar:

Configuration in ablog

changes in conf.py

html_theme = 'sphinx_rtd_theme'

# add localtoc.html
html_sidebars = {
    '**': [ 'localtoc.html', ...
          ]
    }

# custom.css
html_context = {
  'css_files': ['_static/custom.css'],
}

in the _static directory create custom.css

.wy-menu-vertical h3 {
  margin-bottom: 0px;
}

.wy-menu-vertical h2 {
  margin-top: 10px;
  margin-bottom: 10px;
  padding: 0 0.4em;
}

.wy-menu-vertical h3 a {
  padding: 0.4em 0.5em !important;
}

.ablog a {
  display: inline-block !important;
  padding-left: 0.4em;
}

.ablog li {
  padding: 0 0.5em;
}

enter into site-packages directory of your project environment, locate the ablog directory, open the postcard.html and make the following change:

...
<ul class="ablog"> {# change here #}
{% include "postcard2.html" %}
...

Changes in sphinx_rtd_theme

enter into site-packages directory of your project environment, locate the sphinx_rtd_theme directory, and open the layout.html, change the file according to following code:

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  {% block menu %}
    {#
      The singlehtml builder doesn't handle this toctree call when the
      toctree is empty. Skip building this for now.
    #}
    {% if 'singlehtml' not in builder %}
      {% set global_toc = toctree(maxdepth=theme_navigation_depth|int,
                                  collapse=theme_collapse_navigation|tobool,
                                  includehidden=theme_includehidden|tobool,
                                  titles_only=theme_titles_only|tobool) %}
    {% endif %}
    {% if global_toc %}
      {{ global_toc }}
    {% else %}
      <!-- Local TOC -->
      <!-- <div class="local-toc">{{ toc }}</div> --> {# comment out to avoid double entries of toc #}
    {% endif %}
  {% endblock %}
  {% include 'localtoc.html' %} {# added #}
  {% include 'postcard.html' %} {# added #}
  {% include "categories.html" %} {# added #}
  {% include "tagcloud.html" %} {# added #}
  {% include 'recentposts.html' %} {# added #}

</div>

Change the sphinx code to generate the local toctree for our purpose

open site-packages/sphinx/builders/html.py, locate the line with # local TOC and global TOC tree, change according the following code:

    # local TOC and global TOC tree, with local toctree
    self_toc = TocTree(self.env).get_toc_for(docname, self)
    toc = self.render_partial(self_toc)['fragment']
    self._toctree_add_classes(self_toc, docname, 2)
    local_toctree = self.render_partial(self_toc)['fragment']

    return dict(
        parents = parents,
        prev = prev,
        next = next,
        title = title,
        meta = meta,
        body = body,
        metatags = metatags,
        rellinks = rellinks,
        sourcename = sourcename,
        toc = toc,
        local_toctree = local_toctree,      # added
        # only display a TOC if there's more than one item to show
        display_toc = (self.env.toc_num_entries[docname] > 1),
        page_source_suffix = source_suffix,
    )

# adding the logic of generating local toctree
def _toctree_add_classes(self, node, docname, depth):
    # type: (nodes.Node, int) -> None
    """Add 'toctree-l%d' and 'current' classes to the toctree."""
    for subnode in node.children:
        if isinstance(subnode, (addnodes.compact_paragraph,
                                nodes.list_item)):
            # for <p> and <li>, indicate the depth level and recurse
            subnode['classes'].append('toctree-l%d' % (depth - 1))
            self._toctree_add_classes(subnode, docname, depth)
        elif isinstance(subnode, nodes.bullet_list):
            # for <ul>, just recurse
            self._toctree_add_classes(subnode, docname, depth + 1)
        elif isinstance(subnode, nodes.reference):
            # for <a>, identify which entries point to the current
            # document and therefore may not be collapsed
            if subnode['refuri'] == docname:
                if not subnode['anchorname']:
                    # give the whole branch a 'current' class
                    # (useful for styling it differently)
                    branchnode = subnode
                    while branchnode:
                        branchnode['classes'].append('current')
                        branchnode = branchnode.parent
                # mark the list_item as "on current page"
                if subnode.parent.parent.get('iscurrent'):
                    # but only if it's not already done
                    return
                while subnode:
                    subnode['iscurrent'] = True
                    subnode = subnode.parent

open site-packages/sphinx/themes/basic/localtoc.html, change according the following code:

{#
  basic/localtoc.html
  ~~~~~~~~~~~~~~~~~~~

  Sphinx sidebar template: local table of contents.

  :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
  :license: BSD, see LICENSE for details.
#}
{%- if display_toc %}
  <h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>
  {{ local_toctree }}   {# change here #}
{%- endif %}