Show Source

Theming

This collection of pages uses a modified version of the Sphinx haiku theme. Thankfully, it was relatively easy to modify and does not involve copying the whole theme.

  • The config file:

    [theme]
    inherit = haiku
    stylesheet = haikuish.css
    
    [options]
    
  • The CSS overrides:

    @import url("haiku.css");
    
    body {
      max-width: 95vw;
    }
    
    div.relbar1 {
      float: right;
      padding-top: 15px;
      font-size: 0.8em;
      position: relative;
      z-index: 1;
    }
    
    div.header h2 {
        text-transform: none;
    	color: #444;
    }
    
  • The HTML overrides:

    {%- extends "haiku/layout.html" %}
    
    {% block relbar1 %}
     <div class="relbar1">
     {%- if show_source and has_source and sourcename %}
       <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">{{ _('Show Source') }}</a>
     {%- endif %}
     </div>
    {% endblock %}
    

Extensions

Disabling Searching for Particular Directories

Sometimes we don’t want to leak data via search pages. This is a very hackish extension that directly modifies the HTML builder object, since there does not appear to be a better way.

import sphinx
import types

def modBuilder(app):
  try:
    old_index_page = app.builder.index_page
    def new_index_page(self, pagename, doctree, title):
      if (not pagename.startswith("secret/")) :
         old_index_page(pagename, doctree, title)
    app.builder.index_page  = types.MethodType(new_index_page, app.builder)
  except Exception:
    # Alternatively, don't do that and do this instead to disable
    # search functionality altogether.
    app.builder.search = False

def setup(app):
  app.connect('builder-inited', modBuilder)
  return {'version': "1", 'parallel_read_safe': True}

Separately, the secret/ path and _source/secret/ paths are protected by the web server itself so that unauthenticated clients may not read them; otherwise, there’d be little point!

Removing Document Title From Markup

The theme I am using places the title up top specially, but it also remains in the document tree and so gets rendered first thing. That looks bad. This extension surgically removes the document title from pages without altering the sphinx metadata.

import sphinx
from docutils import nodes

def munge_doc_tree(app, doctree, docname):
    sec1i = doctree.first_child_matching_class(nodes.section)
    if sec1i is None: return
    sec1n = doctree[sec1i]
    if sec1n is None: return
    ts1i = sec1n.first_child_matching_class(nodes.title)
    if ts1i is None: return
    sec1n.pop(ts1i)

def setup(app):
    app.connect('doctree-resolved', munge_doc_tree)
    return {'version': "1", 'parallel_read_safe': True}