sphinx

These are mostly out-dated notes to myself about how to make various changes to the way sphinx renders things. I typically just have to google around until I find cut-and-paste solutions because I’ve never bothered to learn how CSS and everything else actually hangs together.

general

  • To change how the sidebar is rendered, these settings are in conf.py:

    html_sidebars = {
   '**': ['globaltoc.html', 'searchbox.html'],
}

    see for example the sphinx docs

  • For opening external links in new tabs http://jack.rosenth.al/hacking-docutils.html#sphinx-hacks:

    from sphinx.writers.html import HTMLTranslator
class PatchedHTMLTranslator(HTMLTranslator):
    def visit_reference(self, node):
        if node.get('newtab') or not (node.get('target') or node.get('internal') or 'refuri' not in node):
            node['target'] = '_blank'
        super().visit_reference(node)

def setup(app):
    app.set_translator('html', PatchedHTMLTranslator)

  • If using this with github pages, we’ll need a .nojekyll file in the root of the pages repo.

classic theme

(possibly only relevant to the classic theme)

The “relbar” is the bar at the top and/or bottom that has the link to home as well as possibly “next | prev”. To change the text/link of the home, add the following to _templates/layout:

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="localhost:8080">grahamlopez.org</a> &raquo;</li>
{% endblock %}

or you can even disable it completely with:

{% extends "!layout.html" %}
{% block relbar1 %}{% endblock %}
{% block relbar2 %}{% endblock %}

alabaster theme

(possibly only relevant to the alabaster theme)

override css from the alabaster.css_t template in _static/custom.css.