README.rst

Maisie Sphinx Theme

Sphinx theme used by Maisie: https://docs.maisie.dev

Based on the Guzzle theme: http://guzzlephp.org

Installation

Install via pip:

$ pip install Maisie-Sphinx-Theme

or if you have the code checked out locally:

$ python setup.py install

Configuration

Add the following to your conf.py:

import maisie_sphinx_theme

html_theme_path = maisie_sphinx_theme.html_theme_path()
html_theme = 'maisie_sphinx_theme'

# Register the theme as an extension to generate a sitemap.xml
extensions.append("maisie_sphinx_theme")

# Maisie theme options (see theme.conf for more information)
html_theme_options = {
    # Set the name of the project to appear in the sidebar
    "project_nav_name": "Project Name",
}

There are a lot more ways to customize this theme, as this more comprehensive example shows:

import maisie_sphinx_theme

html_theme_path = maisie_sphinx_theme.html_theme_path()
html_theme = 'maisie_sphinx_theme'

# Register the theme as an extension to generate a sitemap.xml
extensions.append("maisie_sphinx_theme")

# Maisie theme options (see theme.conf for more information)
html_theme_options = {

    # Set the path to a special layout to include for the homepage
    "index_template": "special_index.html",

    # Set the name of the project to appear in the left sidebar.
    "project_nav_name": "Project Name",

    # Set your Disqus short name to enable comments
    "disqus_comments_shortname": "my_disqus_comments_short_name",

    # Set you GA account ID to enable tracking
    "google_analytics_account": "my_ga_account",

    # Path to a touch icon
    "touch_icon": "",

    # Specify a base_url used to generate sitemap.xml links. If not
    # specified, then no sitemap will be built.
    "base_url": "",

    # Allow a separate homepage from the master_doc
    "homepage": "index",

    # Allow the project link to be overriden to a custom URL.
    "projectlink": "http://myproject.url",

    # Visible levels of the global TOC; -1 means unlimited
    "globaltoc_depth": 3,

    # If False, expand all TOC entries
    "globaltoc_collapse": False,

    # If True, show hidden TOC entries
    "globaltoc_includehidden": False,
}

Customizing the layout

You can customize the theme by overriding Jinja template blocks. For example, "layout.html" contains several blocks that can be overridden or extended.

Place a "layout.html" file in your project's "/_templates" directory.

mkdir source/_templates
touch source/_templates/layout.html

Then, configure your "conf.py":

templates_path = ['_templates']

Finally, edit your override file "source/_templates/layout.html":

{# Import the theme's layout. #}
{% extends "!layout.html" %}

{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}

Note

If you are using Readthedocs, then you might run into an issue where they don't currently allow you to extend layout.html.