Material for Sphinx

This theme provides a responsive Material Design theme for Sphinx documentation. It derives heavily from Material for MkDocs , and also uses code from Guzzle Sphinx Theme .

Roadmap

Material for Sphinx is a work in progress. While I believe that it is ready for use, there are a number of important limitation. The most important it to improve the CSS generation to use SASS . It uses some python to modify Sphinx output, which is not ideal.

The other issues are:

• improving the documentation;

• providing examples;

• sidebar customization;

• improving the search box; and

• ensuring that all Sphinx blocks work as intended.

You can see how it works on statsmodels .

Getting Started

Install from git

pip install git+https://github.com/bashtage/sphinx-material.git

Update your conf.py with the required changes:

html_theme = 'sphinx_material'

There are a lot more ways to customize this theme. See Customization or theme.conf for more details.

html_theme = 'sphinx_material'

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

    # Set the name of the project to appear in the navigation.
    'nav_title': 'Project Name',

    # Set you GA account ID to enable tracking
    'google_analytics_account': 'UA-XXXXX',

    # Specify a base_url used to generate sitemap.xml. If not
    # specified, then no sitemap will be built.
    'base_url': 'https://project.github.io/project',

    # Set the color and the accent color
    'color_primary': 'blue',
    'color_accent': 'light-blue',

    # Set the repo location to get a badge with stats
    'repo_url': 'https://github.com/project/project/',
    'repo_name': 'Project',

    # 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,
}

Customization

There are two methods to alter the theme. The first, and simplest, uses the options exposed through html_theme_options in conf.py . This site’s options are:

html_theme_options = {
    'base_url': 'http://bashtage.github.io/sphinx-material/',
    'repo_url': 'https://github.com/bashtage/sphinx-material/',
    'repo_name': 'Material for Sphinx',
    'google_analytics_account': 'UA-XXXXX',
    'html_minify': True,
    'css_minify': True,
    'nav_title': 'Material Sphinx Demo',
    'logo_icon': '&#xe869',
    'globaltoc_depth': 2
}

The complete list of options with detailed explanations appears in theme.conf .

Configuration Options

nav_title

Set the name to appear in the left sidebar/header. If not provided, uses html_short_title if defined, or html_title.

touch_icon

Path to a touch icon, should be 152x152 or larger.

google_analytics_account

Set to enable google analytics.

repo_url

Set the repo url for the link to appear.

repo_name

The name of the repo. If must be set if repo_url is set.

repo_type

Must be one of github, gitlab or bitbucket.

base_url

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

globaltoc_depth

The maximum depth of the global TOC; set it to -1 to allow unlimited depth.

globaltoc_collapse

If true, TOC entries that are not ancestors of the current page are collapsed.

globaltoc_includehidden

If true, the global TOC tree will also contain hidden entries.

theme_color

The theme color for mobile browsers. Hex Color without the leading #.

color_primary

Primary color. Options are red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey, and white.

color_accent

Accent color. Options are red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, and deep-orange.

html_minify

Minify pages after creation using htmlmin.

html_prettify

Prettify pages, usually only for debugging.

css_minify

Minify css files found in the output directory.

logo_icon

Set the logo icon. Should be a pre-escaped html string that indicates a unicode point, e.g., '&#xe869' which is used on this site. The code point refers to the Material Icons font. This set provides a reasonable set of utility icons. Most sites should not use logo_icon and instead should set html_logo in conf.py to point to a custom SVG icon. Note that logo_icon takes precedent over html_logo and so it should be left empty when using html_logo .

master_doc

Include the master document at the top of the page in the breadcrumb bar. You must also set this to true if you want to override the rootrellink block, in which case the content of the overridden block will appear

nav_links

A list of dictionaries where each has three keys:

• href : The URL or pagename (str)

• title : The title to appear (str)

• internal : Flag indicating to use pathto to find the page. Set to False for external content. (bool)

heroes

A dict[str,str] where the key is a pagename and the value is the text to display in the page’s hero location.

version_dropdown

A flag indicating whether the version drop down should be included. You must supply a JSON file to use this feature.

version_dropdown_text

The text in the version dropdown button

version_json

The location of the JSON file that contains the version information. The default assumes there is a file versions.json located in the root of the site.

version_info

A dictionary used to populate the version dropdown. If this variable is provided, the static dropdown is used and any JavaScript information is ignored.

table_classes

A list of classes to not strip from tables. All other classes are stripped, and the default table has no class attribute. Custom table classes need to provide the full style for the table.

table_no_strip

A list of classes to deactivate the complete table handling by sphinx-material for this specific table, so that all set table classes are kept. Default value: no-sphinx-material-strip .

Sidebars

Note

You must explicitly include globaltoc.html in html_sidebars if you want the toc to show up.

You must set html_sidebars in order for the side bar to appear. There are four in the complete set.

html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}

You can exclude any to hide a specific sidebar. For example, if this is changed to

html_sidebars = {
    "**": ["globaltoc.html"]
}

then only the global ToC would appear on all pages ( ** is a glob pattern).

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 %}

New Blocks

The theme has a small number of new blocks to simplify some types of customization:

footerrel

Previous and next in the footer.

font

The default font inline CSS and the class to the google API. Use this block when changing the font.

fonticon

Block that contains the icon font. Use this to add additional icon fonts (e.g., FontAwesome ). You should probably call {{ super() }} at the end of the block to include the default icon font as well.

Version Dropdown

A version dropdown is available that lets you store multiple versions in a single site. The standard structure of the site, relative to the base is usually:

/
/devel
/v1.0.0
/v1.1.0
/v1.1.1
/v1.2.0

To use the version dropdown, you must set version_dropdown to True in the sites configuration.

There are two approaches, one which stores the version information in a JavaScript file and one which uses a dictionary in the configuration.

Using a Javascript File

The data used is read via javascript from a file. The basic structure of the file is a dictionary of the form [label, path].

This dictionary tells the dropdown that the release version is in the root of the site, the other versions are archived under their version number, and the development version is located in /devel.

Note

The advantage of this approach is that you can separate version information from the rendered documentation. This makes is easy to change the version dropdown in _older_ versions of the documentation to reflect additional versions that are released later. Changing the Javascript file changes the version dropdown content in all versions. This approach is used in statsmodels .

Using conf.py

Warning

This method has precedence over the JavaScript approach. If version_info is not empty in a site’s html_theme_options , then the static approach is used.

The alternative uses a dictionary where the key is the title and the value is the target. The dictionary is part of the size configuration’s html_theme_options .

The dictionary structure is nearly identical. Here you can use relative paths like in the JavaScript version. You can also use absolute paths.

Note

This approach is easier if you only want to have a fixed set of documentation, e.g., stable and devel.

Specimen

Body copy

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero, mollis sed massa vel, ornare viverra ex . Mauris a ullamcorper lacus. Nullam urna elit, malesuada eget finibus ut, ullamcorper ac tortor. Vestibulum sodales pulvinar nisl, pharetra aliquet est. Quisque volutpat erat ac nisi accumsan tempor.

Sed suscipit , orci non pretium pretium, quam mi gravida metus, vel venenatis justo est condimentum diam. Maecenas non ornare justo. Nam a ipsum eros. Nulla aliquam orci sit amet nisl posuere malesuada. Proin aliquet nulla velit, quis ultricies orci feugiat et. Ut tincidunt sollicitudin tincidunt. Aenean ullamcorper sit amet nulla at interdum.

Headings

The 3rd level

The 4th level

The 5th level

The 6th level

Headings with secondary text

The 3rd level with secondary text

The 4th level with secondary text

The 5th level with secondary text

The 6th level with secondary text

Blockquotes

Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie imperdiet consectetur.

Blockquote nesting

Sed aliquet , neque at rutrum mollis, neque nisi tincidunt nibh, vitae faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem libero fermentum urna, ut efficitur elit ligula et nunc.

Mauris dictum mi lacus, sit amet pellentesque urna vehicula fringilla. Ut sit amet placerat ante. Proin sed elementum nulla. Nunc vitae sem odio. Suspendisse ac eros arcu. Vivamus orci erat, volutpat a tempor et, rutrum. eu odio.

Suspendisse rutrum facilisis risus , eu posuere neque commodo a. Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo bibendum, sodales mauris ut, tincidunt massa.

Other content blocks

Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl, sit amet laoreet nibh.

Praesent at return target , sodales nibh vel, tempor felis. Fusce vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices. Donec consectetur mauris non neque imperdiet, eget volutpat libero.

var _extends = function(target) {
  for (var i = 1; i < arguments.length; i++) {
    var source = arguments[i];
    for (var key in source) {
      target[key] = source[key];
    }
  }
  return target;
};

Lists

Unordered lists

• Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.

  • Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.

  • Nam vulputate tincidunt fringilla.

  • Nullam dignissim ultrices urna non auctor.

• Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at aliquam ac, aliquet sed mauris.

• Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh lacinia sed. Aenean in finibus diam.

Ordered lists

1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla consectetur feugiat sodales.

2. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aliquam ornare feugiat quam et egestas. Nunc id erat et quam pellentesque lacinia eu vel odio.

   1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.

      1. Mauris dictum mi lacus

      2. Ut sit amet placerat ante

      3. Suspendisse ac eros arcu

   2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Sed aliquet, neque at rutrum mollis, neque nisi tincidunt nibh.

   3. Pellentesque eget var _extends ornare tellus, ut gravida mi.

      var _extends = function(target) {
        for (var i = 1; i < arguments.length; i++) {
          var source = arguments[i];
          for (var key in source) {
            target[key] = source[key];
          }
        }
        return target;
      };
      

3. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.

Definition lists

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at aliquam ac, aliquet sed mauris.

Code blocks

Inline

Morbi eget dapibus felis . Vivamus ``venenatis porttitor`` tortor sit amet rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Pellentesque aliquet quam enim , eu volutpat urna rutrum a.

Nam vehicula nunc :::js return target mauris, a ultricies libero efficitur sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.

Listing

var _extends = function(target) {
  for (var i = 1; i < arguments.length; i++) {
    var source = arguments[i];
    for (var key in source) {
      target[key] = source[key];
    }
  }
  return target;
};

Horizontal rules

Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

---

Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla consectetur feugiat sodales.

Data tables

Sollicitudo / Pellentesi	consectetur	adipiscing	elit	arcu	sed
Vivamus a pharetra	yes	yes	yes	yes	yes
Ornare viverra ex	yes	yes	yes	yes	yes
Mauris a ullamcorper	yes	yes	partial	yes	yes
Nullam urna elit	yes	yes	yes	yes	yes
Malesuada eget finibus	yes	yes	yes	yes	yes
Ullamcorper	yes	yes	yes	yes	yes
Vestibulum sodales	yes		yes		yes
Pulvinar nisl	yes	yes	yes
Pharetra aliquet est	yes	yes	yes	yes	yes
Sed suscipit	yes	yes	yes	yes	yes
Orci non pretium	yes	partial

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.

Left	Center	Right
Lorem	dolor	amet
ipsum	sit

Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl, sit amet laoreet nibh.

Table	with colgroups (Pandoc)
Lorem	ipsum dolor sit amet.
Sed sagittis	eleifend rutrum. Donec vitae suscipit est.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus nec ipsum a eros convallis facilisis eget at leo. Cras eu pulvinar eros, at accumsan dolor. Ut gravida massa sed eros imperdiet fermentum. Donec ac diam ut lorem consequat laoreet. Maecenas at ex diam. Phasellus tincidunt orci felis, nec commodo nisl aliquet ac. Aenean eget ornare tellus. Nullam vel nunc quis nisi sodales finibus in ut metus. Praesent ultrices mollis leo, auctor volutpat eros consectetur in. Sed ac odio nisi. Cras aliquet ultrices nisl ac mattis. Nulla a dui velit. Proin et ipsum quis metus auctor viverra. Proin suscipit massa quis magna mattis, vel tincidunt quam tincidunt. Vestibulum nec feugiat metus, nec scelerisque eros. Ut ultricies ornare aliquam.

Section II

Proin ac mi tempor, ullamcorper ante at, sodales augue. Duis enim turpis, volutpat eget consectetur id, facilisis vel nisl. Sed non leo aliquam, tempus nisl eu, vestibulum enim. Suspendisse et leo imperdiet, pulvinar lacus sed, commodo felis.

Note

Praesent elit mi, pretium nec pellentesque eget, ultricies euismod turpis.

Sub section

In lobortis elementum tempus. Nam facilisis orci neque, eget vestibulum lectus imperdiet sed. Aenean ac eros sollicitudin, accumsan turpis ac, faucibus arcu.

Section III

Donec sodales, velit ac sagittis fermentum, metus ante pharetra ex, ac eleifend erat ligula in lacus. Donec tincidunt urna est, non mollis turpis lacinia sit amet. Duis ac facilisis libero, ut interdum nibh. Sed rutrum dapibus pharetra. Ut ac luctus nisi, vitae volutpat arcu. Vivamus venenatis eu nibh ut consectetur. Cras tincidunt dui nisi, et facilisis eros feugiat nec.

Fusce ante:

• libero

• consequat quis facilisis id

• sollicitudin et nisl.

Aliquam diam mi, vulputate nec posuere id, consequat id elit. Ut feugiat lectus quam, sed aliquet augue placerat nec. Sed volutpat leo ac condimentum ullamcorper. Vivamus eleifend magna tellus, sit amet porta nunc ultrices eget. Nullam id laoreet ex. Nam ultricies, ante et molestie mollis, magna sem porta libero, sed molestie neque risus ut purus. Ut tellus sapien, auctor a lacus eu, iaculis congue ex.

Duis et nisi a odio scelerisque sodales ac ut sapien. Ut eleifend blandit velit luctus euismod. Curabitur at pulvinar mi. Cras molestie lorem non accumsan gravida. Sed vulputate, ligula ut tincidunt congue, metus risus luctus lacus, sed rhoncus ligula turpis non erat. Phasellus est est, sollicitudin ut elementum vel, placerat in orci. Proin molestie posuere dolor sit amet convallis. Donec id urna vel lacus ultrices pulvinar sit amet id metus. Donec in venenatis ante. Nam eu rhoncus leo. Quisque posuere, leo vel porttitor malesuada, nisi urna dignissim justo, vel consectetur purus elit in mauris. Vestibulum lectus arcu, varius ut ligula quis, viverra gravida sem.

Warning

Pellentesque in enim leo.

Images

Default Alignment

Center Alignment

Right Alignment

Additional Samples

Various examples of styling applied to Sphinx constructs. You can view the source of this page to see the specific reStructuredText used to create these examples.

Subpages

Suppages get bread crumbs when they are not at the top level.

Level 1 page

Stepping lower into the hierarchy changes the tab par along the top.

Subsubpage

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Amet risus nullam eget felis. Sollicitudin aliquam ultrices sagittis orci. Blandit massa enim nec dui. Viverra accumsan in nisl nisi scelerisque eu ultrices. Faucibus scelerisque eleifend donec pretium. Fames ac turpis egestas sed. Arcu risus quis varius quam quisque id diam vel. Nisl nisi scelerisque eu ultrices vitae auctor. Adipiscing elit ut aliquam purus. Vivamus at augue eget arcu dictum. Vivamus at augue eget arcu. Hendrerit gravida rutrum quisque non tellus orci. Ut ornare lectus sit amet est placerat in egestas erat.

Consequat id porta nibh venenatis cras. Posuere ac ut consequat semper viverra. Felis eget velit aliquet sagittis id consectetur. Malesuada fames ac turpis egestas maecenas pharetra convallis posuere. At consectetur lorem donec massa sapien faucibus et molestie. Bibendum at varius vel pharetra. Rhoncus est pellentesque elit ullamcorper dignissim cras tincidunt lobortis. Consectetur lorem donec massa sapien. Ullamcorper dignissim cras tincidunt lobortis feugiat vivamus at augue. Mollis aliquam ut porttitor leo a diam sollicitudin tempor id. Ipsum faucibus vitae aliquet nec. Eu sem integer vitae justo eget magna fermentum iaculis. Adipiscing commodo elit at imperdiet dui accumsan sit amet nulla.

Second Subsubpage

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Amet risus nullam eget felis. Sollicitudin aliquam ultrices sagittis orci. Blandit massa enim nec dui. Viverra accumsan in nisl nisi scelerisque eu ultrices. Faucibus scelerisque eleifend donec pretium. Fames ac turpis egestas sed. Arcu risus quis varius quam quisque id diam vel. Nisl nisi scelerisque eu ultrices vitae auctor. Adipiscing elit ut aliquam purus. Vivamus at augue eget arcu dictum. Vivamus at augue eget arcu. Hendrerit gravida rutrum quisque non tellus orci. Ut ornare lectus sit amet est placerat in egestas erat.

Consequat id porta nibh venenatis cras. Posuere ac ut consequat semper viverra. Felis eget velit aliquet sagittis id consectetur. Malesuada fames ac turpis egestas maecenas pharetra convallis posuere. At consectetur lorem donec massa sapien faucibus et molestie. Bibendum at varius vel pharetra. Rhoncus est pellentesque elit ullamcorper dignissim cras tincidunt lobortis. Consectetur lorem donec massa sapien. Ullamcorper dignissim cras tincidunt lobortis feugiat vivamus at augue. Mollis aliquam ut porttitor leo a diam sollicitudin tempor id. Ipsum faucibus vitae aliquet nec. Eu sem integer vitae justo eget magna fermentum iaculis. Adipiscing commodo elit at imperdiet dui accumsan sit amet nulla.

Headings

This is a first level heading ( h1 ).

Sub-Heading

This is a second level heading ( h2 ).

Sub-Sub-Heading

This is a third level heading ( h3 ).

Code

The theme uses pygments for inline code text and

multiline
code text

Here’s an included example with line numbers.

"""Sphinx Material theme."""

import hashlib
import inspect
import os
import re
import sys
from multiprocessing import Manager
from typing import List, Optional
from xml.etree import ElementTree

import bs4
import slugify
from bs4 import BeautifulSoup
from sphinx.util import console, logging

from ._version import get_versions

__version__ = get_versions()["version"]
del get_versions

ROOT_SUFFIX = "--page-root"

USER_TABLE_CLASSES = []
USER_TABLE_NO_STRIP_CLASSES = ["no-sphinx-material-strip"]


def setup(app):
    """Setup connects events to the sitemap builder"""
    app.connect("html-page-context", add_html_link)
    app.connect("build-finished", create_sitemap)
    app.connect("build-finished", reformat_pages)
    app.connect("build-finished", minify_css)
    app.connect("builder-inited", update_html_context)
    app.connect("config-inited", update_table_classes)
    manager = Manager()
    site_pages = manager.list()
    sitemap_links = manager.list()
    app.multiprocess_manager = manager
    app.sitemap_links = sitemap_links
    app.site_pages = site_pages
    app.add_html_theme(
        "sphinx_material", os.path.join(html_theme_path()[0], "sphinx_material")
    )
    return {
        "version": __version__,
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }


def add_html_link(app, pagename, templatename, context, doctree):
    """As each page is built, collect page names for the sitemap"""
    base_url = app.config["html_theme_options"].get("base_url", "")
    if base_url:
        app.sitemap_links.append(base_url + pagename + ".html")
    minify = app.config["html_theme_options"].get("html_minify", False)
    prettify = app.config["html_theme_options"].get("html_prettify", False)
    if minify and prettify:
        raise ValueError("html_minify and html_prettify cannot both be True")
    if minify or prettify:
        app.site_pages.append(os.path.join(app.outdir, pagename + ".html"))


def create_sitemap(app, exception):
    """Generates the sitemap.xml from the collected HTML page links"""
    if (
        not app.config["html_theme_options"].get("base_url", "")
        or exception is not None
        or not app.sitemap_links
    ):
        return

    filename = app.outdir + "/sitemap.xml"
    print(
        "Generating sitemap for {0} pages in "
        "{1}".format(len(app.sitemap_links), console.colorize("blue", filename))
    )

    root = ElementTree.Element("urlset")
    root.set("xmlns", "http://www.sitemaps.org/schemas/sitemap/0.9")

    for link in app.sitemap_links:
        url = ElementTree.SubElement(root, "url")
        ElementTree.SubElement(url, "loc").text = link
    app.sitemap_links[:] = []

    ElementTree.ElementTree(root).write(filename)


def reformat_pages(app, exception):
    if exception is not None or not app.site_pages:
        return
    minify = app.config["html_theme_options"].get("html_minify", False)
    last = -1
    npages = len(app.site_pages)
    transform = "Minifying" if minify else "Prettifying"
    print("{0} {1} files".format(transform, npages))
    transform = transform.lower()
    # TODO: Consider using parallel execution
    for i, page in enumerate(app.site_pages):
        if int(100 * (i / npages)) - last >= 1:
            last = int(100 * (i / npages))
            color_page = console.colorize("blue", page)
            msg = "{0} files... [{1}%] {2}".format(transform, last, color_page)
            sys.stdout.write("\033[K" + msg + "\r")
        with open(page, "r", encoding="utf-8") as content:
            if minify:
                from css_html_js_minify.html_minifier import html_minify

                html = html_minify(content.read())
            else:
                soup = BeautifulSoup(content.read(), features="lxml")
                html = soup.prettify()
        with open(page, "w", encoding="utf-8") as content:
            content.write(html)
    app.site_pages[:] = []
    print()


def minify_css(app, exception):
    if exception is not None or not app.config["html_theme_options"].get(
        "css_minify", False
    ):
        app.multiprocess_manager.shutdown()
        return
    import glob
    from css_html_js_minify.css_minifier import css_minify

    css_files = glob.glob(os.path.join(app.outdir, "**", "*.css"), recursive=True)
    print("Minifying {0} css files".format(len(css_files)))
    for css_file in css_files:
        colorized = console.colorize("blue", css_file)
        msg = "minifying css file {0}".format(colorized)
        sys.stdout.write("\033[K" + msg + "\r")
        with open(css_file, "r", encoding="utf-8") as content:
            css = css_minify(content.read())
        with open(css_file, "w", encoding="utf-8") as content:
            content.write(css)
    print()
    app.multiprocess_manager.shutdown()


def update_html_context(app):
    config = app.config
    config.html_context = {**get_html_context(), **config.html_context}


def update_table_classes(app, config):
    table_classes = config.html_theme_options.get("table_classes")
    if table_classes:
        USER_TABLE_CLASSES.extend(table_classes)

    table_no_strip_classes = config.html_theme_options.get("table_no_strip")
    if table_no_strip_classes:
        USER_TABLE_NO_STRIP_CLASSES.extend(table_no_strip_classes)


def html_theme_path():
    return [os.path.dirname(os.path.abspath(__file__))]


def ul_to_list(node: bs4.element.Tag, fix_root: bool, page_name: str) -> List[dict]:
    out = []
    for child in node.find_all("li", recursive=False):
        if callable(child.isspace) and child.isspace():
            continue
        formatted = {}
        if child.a is not None:
            formatted["href"] = child.a["href"]
            formatted["contents"] = "".join(map(str, child.a.contents))
            if fix_root and formatted["href"] == "#" and child.a.contents:
                slug = slugify.slugify(page_name) + ROOT_SUFFIX
                formatted["href"] = "#" + slug
            formatted["current"] = "current" in child.a.get("class", [])
        if child.ul is not None:
            formatted["children"] = ul_to_list(child.ul, fix_root, page_name)
        else:
            formatted["children"] = []
        out.append(formatted)
    return out


class CaptionList(list):
    _caption = ""

    def __init__(self, caption=""):
        super().__init__()
        self._caption = caption

    @property
    def caption(self):
        return self._caption

    @caption.setter
    def caption(self, value):
        self._caption = value


def derender_toc(
    toc_text, fix_root=True, page_name: str = "md-page-root--link"
) -> List[dict]:
    nodes = []
    try:
        toc = BeautifulSoup(toc_text, features="html.parser")
        for child in toc.children:
            if callable(child.isspace) and child.isspace():
                continue
            if child.name == "p":
                nodes.append({"caption": "".join(map(str, child.contents))})
            elif child.name == "ul":
                nodes.extend(ul_to_list(child, fix_root, page_name))
            else:
                raise NotImplementedError
    except Exception as exc:
        logger = logging.getLogger(__name__)
        logger.warning(
            "Failed to process toctree_text\n" + str(exc) + "\n" + str(toc_text)
        )

    return nodes


def walk_contents(tags):
    out = []
    for tag in tags.contents:
        if hasattr(tag, "contents"):
            out.append(walk_contents(tag))
        else:
            out.append(str(tag))
    return "".join(out)


def table_fix(body_text, page_name="md-page-root--link"):
    # This is a hack to skip certain classes of tables
    ignore_table_classes = {"highlighttable", "longtable", "dataframe"} | set(
        USER_TABLE_NO_STRIP_CLASSES
    )
    try:
        body = BeautifulSoup(body_text, features="html.parser")
        for table in body.select("table"):
            classes = set(table.get("class", tuple()))
            if classes.intersection(ignore_table_classes):
                continue
            classes = [tc for tc in classes if tc in USER_TABLE_CLASSES]
            if classes:
                table["class"] = classes
            else:
                del table["class"]
        first_h1: Optional[bs4.element.Tag] = body.find("h1")
        headers = body.find_all(re.compile("^h[1-6]$"))
        for i, header in enumerate(headers):
            for a in header.select("a"):
                if "headerlink" in a.get("class", ""):
                    header["id"] = a["href"][1:]
        if first_h1 is not None:
            slug = slugify.slugify(page_name) + ROOT_SUFFIX
            first_h1["id"] = slug
            for a in first_h1.select("a"):
                a["href"] = "#" + slug

        divs = body.find_all("div", {"class": "section"})
        for div in divs:
            div.unwrap()

        return str(body)
    except Exception as exc:
        logger = logging.getLogger(__name__)
        logger.warning("Failed to process body_text\n" + str(exc))
        return body_text


# These final lines exist to give sphinx a stable str representation of
# these two functions across runs, and to ensure that the str changes
# if the source does.
#
# Note that this would be better down with a metaclass factory
table_fix_src = inspect.getsource(table_fix)
table_fix_hash = hashlib.sha512(table_fix_src.encode()).hexdigest()
derender_toc_src = inspect.getsource(derender_toc)
derender_toc_hash = hashlib.sha512(derender_toc_src.encode()).hexdigest()


class TableFixMeta(type):
    def __repr__(self):
        return f"table_fix, hash: {table_fix_hash}"

    def __str__(self):
        return f"table_fix, hash: {table_fix_hash}"


class TableFix(object, metaclass=TableFixMeta):
    def __new__(cls, *args, **kwargs):
        return table_fix(*args, **kwargs)


class DerenderTocMeta(type):
    def __repr__(self):
        return f"derender_toc, hash: {derender_toc_hash}"

    def __str__(self):
        return f"derender_toc, hash: {derender_toc_hash}"


class DerenderToc(object, metaclass=DerenderTocMeta):
    def __new__(cls, *args, **kwargs):
        return derender_toc(*args, **kwargs)


def get_html_context():
    return {"table_fix": TableFix, "derender_toc": DerenderToc}

It also works with existing Sphinx highlighting:

<html>
  <body>Hello World</body>
</html>

def hello():
    """Greet."""
    return "Hello World"

/**
 * Greet.
 */
function hello(): {
  return "Hello World";
}

Admonitions

The theme uses the admonition classes for Sphinx admonitions.

Note

Note

This is a note .

Todo

Todo

It is essential to complete todo items.

Warning

Warning

This is a warning .

Danger

Danger

This is danger -ous.

Attention

Attention

Do I have your attention ?

Caution

Caution

Use caution !

Error

Error

You have made a grave error .

Hint

Hint

Can you take a hint ?

Important

Important

It is important to correctly use admonitions.

Tip

Tip

Please tip your waiter.

Custom Admonitions

Custom

You can create your own admonitions with the default style.

Footnotes

I have footnoted a first item 1 and second item 2 . This also references the second item 2 .

Footnotes

1

My first footnote.

2 ( 1 , 2 )

My second footnote.

Icons

The following template HTML:

<span style="font-size: 2rem;" class="md-icon">&#xe869;</span>

translates to a the site’s icon:



The material icon font provides hundreds to choose from. You can use the <i> tag or the <span> tag.

         

Tables

Here are some examples of Sphinx tables . The Sphinx Material all classes and only applies the default style to classless tables. If you want to use a custom table class, you will need to do two thing. First, apply it using .. cssclass:: custom-class and then add it to your configuration’s table_classes variable.

Grid

A grid table:

Header1	Header2	Header3	Header4
row1, cell1	cell2	cell3	cell4
row2 …	…	…
…	…	…

Simple

A simple table:

H1	H2	H3
cell1	cell2	cell3
…	…	…
…	…	…

User-styled Table

Note

table_classes is set to [“plain”] in the site’s configuration. Only plain remains as the class of the table. Other standard classes applied by Sphinx are removed.

This is feature demonstration. There is no css for the plain class, and so this is completely unstyled.

User	Styled	Table
cell1	cell2	cell3
…	…	…
…	…	…

List Tables

A List Table

Column 1	Column 2
Item 1	Item 2

Alignment

Warning

Alignment is not currently working as expected.

Center Aligned

Column 1	Column 2
Item 1	Item 2

Right Aligned

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Code Documentation

An example Python function.

format_exception ( etype , value , tb [ , limit=None ] )

Format the exception with a traceback.

Parameters

• etype – exception type

• value – exception value

• tb – traceback object

• limit ( integer or None ) – maximum number of stack frames to show

Return type

list of strings

An example JavaScript function.

class MyAnimal ( name [ , age ] )

Arguments

• name ( string() ) – The name of the animal

• age ( number() ) – an optional age for the animal

Glossaries

environment

A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.

source directory

The directory which, including its subdirectories, contains all source files for one Sphinx project.

Math

\[ \begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\(a - b)^2 = a^2 - 2ab + b^2\end{aligned}\end{align} \]

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

\begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}

Production Lists

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["," target]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite

Python Methods

Table of Contents

• Python Methods

  • Client

send_message ( sender , recipient , message_body [ , priority=1 ] )

Send a message to a recipient

Parameters

• sender ( str ) – The person sending the message

• recipient ( str ) – The recipient of the message

• message_body ( str ) – The body of the message

• priority ( integer or None ) – The priority of the message, can be a number 1-5

Returns

the message id

Return type

int

Raises

• ValueError – if the message_body exceeds 160 characters

• TypeError – if the message_body is not a basestring

Client

class Foo. Client

Lorem ipsum dolor. Lorem ipsum dolor:

client = foo.create_client('baz')

Available methods:

• bar()

bar ( ** kwargs )

Lorem ipsum dolor. Lorem ipsum dolor.

Request Syntax

response = client.accept_vpc_peering_connection(
    DryRun=True|False,
    VpcPeeringConnectionId='string'
)

Parameters

• DryRun ( boolean ) – Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation . Otherwise, it is UnauthorizedOperation .

• VpcPeeringConnectionId ( string ) – The ID of the VPC peering connection.

Return type

dict

Returns

Response Syntax

{
    'VpcPeeringConnection': {
        'AccepterVpcInfo': {
            'CidrBlock': 'string',
            'OwnerId': 'string',
            'VpcId': 'string'
        },
        'ExpirationTime': datetime(2015, 1, 1),
        'RequesterVpcInfo': {
            'CidrBlock': 'string',
            'OwnerId': 'string',
            'VpcId': 'string'
        },
        'Status': {
            'Code': 'string',
            'Message': 'string'
        },
        'Tags': [
            {
                'Key': 'string',
                'Value': 'string'
            },
        ],
        'VpcPeeringConnectionId': 'string'
    }
}

Response Structure

• (dict) –

  • VpcPeeringConnection (dict) – Information about the VPC peering connection.

    • AccepterVpcInfo (dict) – The information of the peer VPC.

      • CidrBlock (string) – The CIDR block for the VPC.

        • OwnerId (string) – The AWS account ID of the VPC owner.

        • VpcId (string) – The ID of the VPC.

        • ExpirationTime (datetime) – The time that an unaccepted VPC peering connection will expire.

        • RequesterVpcInfo (dict) – The information of the requester VPC.

          • CidrBlock (string) – The CIDR block for the VPC.

          • OwnerId (string) – The AWS account ID of the VPC owner.

          • VpcId (string) – The ID of the VPC.

          • Status (dict) – The status of the VPC peering connection.

          • Code (string) – The status of the VPC peering connection.

          • Message (string) – A message that provides more information about the status, if applicable.

          • Tags (list) – Any tags assigned to the resource.

            • (dict) – Describes a tag.

              • Key (string) – The key of the tag.

                Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:

              • Value (string) – The value of the tag.

                Constraints: Tag values are case-sensitive and accept a maximum of 255 Unicode characters.

              • VpcPeeringConnectionId (string) – The ID of the VPC peering connection.

NumPy Docstrings

This page shows how autosummary works with numpydoc and a NumPy-style docstring.

Polynomial (coef[, domain, window])

A power series class.

Jupyter Notebooks

The nbsphinx extension allow notebooks to be seemlessly integrated into a Sphinx website. This page demonstrates how notebooks are rendered.

Mathematics

MathJax can use used to render mathematical equations. Equations can be rendered either in their own line using double dollar signs

\[y_{it} = \alpha_i + \gamma_t + \beta x_{it} + \epsilon_{it}\]

or inline using single dollar signs ( \(\LaTeX\) ).

DataFrames

pandas DataFrames are rendered with useful markup.

import numpy as np
import pandas as pd

df = pd.DataFrame({'ints': [1, 2, 3],
                   'floats': [np.pi, np.exp(1), (1+np.sqrt(5))/2],
                   'strings': ['aardvark', 'bananarama', 'charcuterie' ]})

df

	ints	floats	strings
0	1	3.141593	aardvark
1	2	2.718282	bananarama
2	3	1.618034	charcuterie

Plots and Figures

matplotlib can be used to produce plots in notebooks

This example comes from the matplotlib gallery .

%matplotlib inline

import numpy as np
import matplotlib.pyplot as plt
from matplotlib import cm

fig, ax = plt.subplots(figsize=(12,8))

data = np.clip(np.random.randn(250, 250), -1, 1)

cax = ax.imshow(data, interpolation='nearest', cmap=cm.coolwarm)
ax.set_title('Gaussian noise with vertical colorbar', fontsize=16)
plt.tick_params(labelsize=16)

# Add colorbar, make sure to specify tick locations to match desired ticklabels
cbar = fig.colorbar(cax, ticks=[-1, 0, 1])
cbar.ax.set_yticklabels(['< -1', '0', '> 1'])  # vertically oriented colorbar
cbar.ax.tick_params(labelsize=16)

Markdown

Sphinx can be configured to use markdown using the recommonmark extension. recommonmark is strict and does not natively support tables or common extensions to markdown.

---

Body copy

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero, mollis sed massa vel, ornare viverra ex . Mauris a ullamcorper lacus. Nullam urna elit, malesuada eget finibus ut, ullamcorper ac tortor. Vestibulum sodales pulvinar nisl, pharetra aliquet est. Quisque volutpat erat ac nisi accumsan tempor.

Sed suscipit , orci non pretium pretium, quam mi gravida metus, vel venenatis justo est condimentum diam. Maecenas non ornare justo. Nam a ipsum eros. Nulla aliquam orci sit amet nisl posuere malesuada. Proin aliquet nulla velit, quis ultricies orci feugiat et. Ut tincidunt sollicitudin tincidunt. Aenean ullamcorper sit amet nulla at interdum.

Headings

The 3rd level

The 4th level

The 5th level

The 6th level

Headings with secondary text

The 3rd level with secondary text

The 4th level with secondary text

The 5th level with secondary text

The 6th level with secondary text

Blockquotes

Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie imperdiet consectetur.

Blockquote nesting

Sed aliquet , neque at rutrum mollis, neque nisi tincidunt nibh, vitae faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem libero fermentum urna, ut efficitur elit ligula et nunc.

Mauris dictum mi lacus, sit amet pellentesque urna vehicula fringilla. Ut sit amet placerat ante. Proin sed elementum nulla. Nunc vitae sem odio. Suspendisse ac eros arcu. Vivamus orci erat, volutpat a tempor et, rutrum. eu odio.

Suspendisse rutrum facilisis risus , eu posuere neque commodo a. Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo bibendum, sodales mauris ut, tincidunt massa.

Other content blocks

Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl, sit amet laoreet nibh.

var _extends = function(target) {
  for (var i = 1; i < arguments.length; i++) {
    var source = arguments[i];
    for (var key in source) {
      target[key] = source[key];
    }
  }
  return target;
};

Praesent at :::js return target , sodales nibh vel, tempor felis. Fusce vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices. Donec consectetur mauris non neque imperdiet, eget volutpat libero.

Lists

Unordered lists

• Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.

  • Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.

  • Nam vulputate tincidunt fringilla.

  • Nullam dignissim ultrices urna non auctor.

• Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at aliquam ac, aliquet sed mauris.

• Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh lacinia sed. Aenean in finibus diam.

Ordered lists

1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla consectetur feugiat sodales.

2. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aliquam ornare feugiat quam et egestas. Nunc id erat et quam pellentesque lacinia eu vel odio.

   1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.

      1. Mauris dictum mi lacus

      2. Ut sit amet placerat ante

      3. Suspendisse ac eros arcu

   2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Sed aliquet, neque at rutrum mollis, neque nisi tincidunt nibh.

   3. Pellentesque eget :::js var _extends ornare tellus, ut gravida mi.

   var _extends = function(target) {
     for (var i = 1; i < arguments.length; i++) {
       var source = arguments[i];
       for (var key in source) {
         target[key] = source[key];
       }
     }
     return target;
   };
   

3. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.

Definition lists

Not supported in commonmark, but you can use a rst definition list inside a fenced eval_rst block.

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at aliquam ac, aliquet sed mauris.

Code blocks

Inline

Morbi eget dapibus felis . Vivamus venenatis porttitor tortor sit amet rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Pellentesque aliquet quam enim , eu volutpat urna rutrum a.

Nam vehicula nunc :::js return target mauris, a ultricies libero efficitur sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.

Listing

var _extends = function(target) {
  for (var i = 1; i < arguments.length; i++) {
    var source = arguments[i];
    for (var key in source) {
      target[key] = source[key];
    }
  }
  return target;
};

Horizontal rules

Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

---

Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla consectetur feugiat sodales.

Data tables

Note : Markdown table syntax requires sphinx_markdown_tables

Sollicitudo / Pellentesi	consectetur	adipiscing	elit	arcu	sed
Vivamus a pharetra	yes	yes	yes	yes	yes
Ornare viverra ex	yes	yes	yes	yes	yes
Mauris a ullamcorper	yes	yes	partial	yes	yes
Nullam urna elit	yes	yes	yes	yes	yes
Malesuada eget finibus	yes	yes	yes	yes	yes
Ullamcorper	yes	yes	yes	yes	yes
Vestibulum sodales	yes	-	yes	-	yes
Pulvinar nisl	yes	yes	yes	-	-
Pharetra aliquet est	yes	yes	yes	yes	yes
Sed suscipit	yes	yes	yes	yes	yes
Orci non pretium	yes	partial	-	-	-

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.

Left	Center	Right
Lorem	dolor	amet
ipsum	sit

Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl, sit amet laoreet nibh.

Table	with colgroups (Pandoc)
Lorem	ipsum dolor sit amet.
Sed sagittis	eleifend rutrum. Donec vitae suscipit est.

rst Cheatsheet

The rst Cheatsheet covers a wide range of rst markup. It and its contents are CC licensed .

Inline Markup

Inline markup allows words and phrases within text to have character styles (like italics and boldface) and functionality (like hyperlinks).

*emphasis*	emphasis
**strong emphasis**	strong emphasis
`interpreted text`	The rendering and meaning of interpreted text is domain- or application-dependent.
``inline literal``	inline literal
reference_	reference
`phrase reference`_	phrase reference
anonymous__	anonymous
_`inline internal target`	inline internal target
|substitution reference|	The result is substituted in from the substitution definition.
footnote reference [1]_	footnote reference 1
citation reference [CIT2002]_	citation reference [CIT2002]
http://docutils.sf.net/	http://docutils.sf.net/

Escaping with Backslashes

reStructuredText uses backslashes (”\”) to override the special meaning given to markup characters and get the literal characters themselves. To get a literal backslash, use an escaped backslash (”\\”). For example:

*escape* ``with`` "\"	escape with “"
\*escape* \``with`` "\\"	*escape* ``with`` “\”

Lists

- This is item 1. A blank line before the first and last items is required. - This is item 2 - Item 3: blank lines between items are optional. - Item 4: Bullets are "-", "*" or "+". Continuing text must be aligned after the bullet and whitespace. - This list item contains nested items - Nested items must be indented to the same level	This is item 1. A blank line before the first and last items is required. This is item 2 Item 3: blank lines between items are optional. Item 4: Bullets are “-”, “*” or “+”. Continuing text must be aligned after the bullet and whitespace. This list item contains nested items Nested items must be indented to the same level
3. This is the first item 4. This is the second item 5. Enumerators are arabic numbers, single letters, or roman numerals 6. List items should be sequentially numbered, but need not start at 1 (although not all formatters will honour the first index). #. This item is auto-enumerated	This is the first item This is the second item Enumerators are arabic numbers, single letters, or roman numerals List items should be sequentially numbered, but need not start at 1 (although not all formatters will honour the first index). This item is auto-enumerated
what Definition lists associate a term with a definition. how The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition.	what Definition lists associate a term with a definition. how The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition.
:Authors: Tony J. (Tibs) Ibbs, David Goodger :Version: 1.0 of 2001/08/08 :Dedication: To my father.	Authors Tony J. (Tibs) Ibbs, David Goodger Version 1.0 of 2001/08/08 Dedication To my father.
-a command-line option "a" -b file options can have arguments and long descriptions --long options can be long also --input=file long options can also have arguments /V DOS/VMS-style options too	-a command-line option “a” -b file options can have arguments and long descriptions --long options can be long also --input= file long options can also have arguments /V DOS/VMS-style options too

Section Structure

Title ===== Titles are underlined (or over- and underlined) with a nonalphanumeric character at least as long as the text. A lone top-level section is lifted up to be the document's title. Any non-alphanumeric character can be used, but Python convention is: * ``#`` with overline, for parts * ``*`` with overline, for chapters * ``=``, for sections * ``-``, for subsections * ``^``, for subsubsections * ``"``, for paragraphs

Title Titles are underlined (or over- and underlined) with a nonalphanumeric character at least as long as the text. A lone top-level section is lifted up to be the document’s title. Any non-alphanumeric character can be used, but Python convention is: # with overline, for parts * with overline, for chapters = , for sections - , for subsections ^ , for subsubsections " , for paragraphs

Blocks

This is a paragraph. Paragraphs line up at their left edges, and are normally separated by blank lines.	This is a paragraph. Paragraphs line up at their left edges, and are normally separated by blank lines.
A paragraph containing only two colons indicates the following indented or quoted text is a literal block or quoted text is a literal block. :: Whitespace, newlines, blank lines, and all kinds of markup (like *this* or \this) is preserved here. You can also tack the ``::`` at the end of a paragraph:: It's very convenient to use this form. Per-line quoting can also be used for unindented blocks:: > Useful for quotes from email and > for Haskell literate programming.	A paragraph containing only two colons indicates that the following indented or quoted text is a literal block. Whitespace, newlines, blank lines, and all kinds of markup (like *this* or \this) is preserved by literal blocks. You can also tack the :: at the end of a paragraph: It's very convenient to use this form. Per-line quoting can also be used for unindented blocks: > Useful for quotes from email and > for Haskell literate programming.
| Line blocks are useful for addresses, | verse, and adornment-free lists. | | Each new line begins with a | vertical bar ("|"). | Line breaks and initial indents | are preserved. | Continuation lines are wrapped portions of long lines; they begin with spaces in place of vertical bars.	Line blocks are useful for addresses, verse, and adornment-free lists. Each new line begins with a vertical bar (“|”). Line breaks and initial indents are preserved. Continuation lines are wrapped portions of long lines; they begin with spaces in place of vertical bars.
Block quotes are just: Indented paragraphs, and they may nest.	Block quotes are just: Indented paragraphs, and they may nest.
Doctest blocks are interactive Python sessions. They begin with "``>>>``" and end with a blank line. >>> print "This is a doctest block." This is a doctest block.	Doctest blocks are interactive Python sessions. They begin with “ >>> ” and end with a blank line. >>> print "This is a doctest block." This is a doctest block.
A transition marker is a horizontal line of 4 or more repeated punctuation characters. ------------ A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.	A transition marker is a horizontal line of 4 or more repeated punctuation characters. A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.

Tables

There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are easy to create but limited (no row spans, etc.).

+------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+

Header 1 Header 2 Header 3 body row 1 column 2 column 3 body row 2 Cells may span columns. body row 3 Cells may span rows. Cells contain blocks. body row 4

===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ======

Inputs Output A B A or B False False False True False True False True True True True True

Explicit Markup

Explicit markup blocks are used for constructs which float (footnotes), have no direct paper-document representation (hyperlink targets, comments), or require specialized processing (directives). They all begin with two periods and whitespace, the “explicit markup start”.

Footnote references, like [5]_. Note that footnotes may get rearranged, e.g., to the bottom of the "page". .. [5] A numerical footnote. Note there's no colon after the ``]``.	Footnote references, like 5 . Note that footnotes may get rearranged, e.g., to the bottom of the “page”. 5 A numerical footnote. Note there’s no colon after the ] .
Autonumbered footnotes are possible, like using [#]_ and [#]_. .. [#] This is the first one. .. [#] This is the second one. They may be assigned 'autonumber labels' - for instance, [#fourth]_ and [#third]_. .. [#third] a.k.a. third_ .. [#fourth] a.k.a. fourth_	Autonumbered footnotes are possible, like using 1 and 2 . 1 This is the first one. 2 This is the second one. They may be assigned ‘autonumber labels’ - for instance, 4 and 3 . 3 a.k.a. third 4 a.k.a. fourth
Auto-symbol footnotes are also possible, like this: [*]_ and [*]_. .. [*] This is the first one. .. [*] This is the second one.	Auto-symbol footnotes are also possible, like this: * and † . * This is the first one. † This is the second one.
Citation references, like [CIT2002]_. Note that citations may get rearranged, e.g., to the bottom of the "page". .. [CIT2002] A citation (as often used in journals). Citation labels contain alphanumerics, underlines, hyphens and fullstops. Case is not significant. Given a citation like [this]_, one can also refer to it like this_. .. [this] here.	Citation references, like [CIT2002] . Note that citations may get rearranged, e.g., to the bottom of the “page”. CIT2002 ( 1 , 2 ) A citation (as often used in journals). Citation labels contain alphanumerics, underlines, hyphens and fullstops. Case is not significant. Given a citation like [this] , one can also refer to it like this . this here.
External hyperlinks, like Python_. .. _Python: http://www.python.org/	External hyperlinks, like Python .
External hyperlinks, like `Python <http://www.python.org/>`_.	External hyperlinks, like Python .
Internal crossreferences, like example_. .. _example: This is an example crossreference target.	Internal crossreferences, like example . This is an example crossreference target.
Python_ is `my favourite programming language`__. .. _Python: http://www.python.org/ __ Python_	Python is my favourite programming language .
Titles are targets, too ======================= Implict references, like `Titles are targets, too`_.	Titles are targets, too Implict references, like Titles are targets, too .
Directives are a general-purpose extension mechanism, a way of adding support for new constructs without adding new syntax. For a description of all standard directives, see reStructuredText Directives ( http://is.gd/2Ecqh ).
For instance: .. image:: magnetic-balls.jpg :width: 40pt	For instance:
Substitutions are like inline directives, allowing graphics and arbitrary constructs within text.
The |biohazard| symbol must be used on containers used to dispose of medical waste. .. |biohazard| image:: biohazard.png :align: middle :width: 12	The symbol must be used on containers used to dispose of medical waste.
Any text which begins with an explicit markup start but doesn’t use the syntax of any of the constructs above, is a comment.
.. This text will not be shown (but, for instance, in HTML might be rendered as an HTML comment)
An "empty comment" does not consume following blocks. (An empty comment is ".." with blank lines before and after.) .. So this block is not "lost", despite its indentation.	An “empty comment” does not consume following blocks. (An empty comment is “..” with blank lines before and after.) So this block is not “lost”, despite its indentation.

Credits

CP Font from LiquiType:	http://www.liquitype.com/workshop/type_design/cp-mono
Magnetic Balls V2 image by fdecomite:	http://www.flickr.com/photos/fdecomite/2926556794/
Sponsored by Net Managers	http://www.netmanagers.com.ar
Typeset using rst2pdf	http://rst2pdf.googlecode.com

© 2009 Roberto Alsina <ralsina@netmanagers.com.ar> / Creative Commons Attribution-Noncommercial-Share Alike 2.5 Argentina License

Based on quickref.txt from docutils

Non-Commercial

Share Alike

reStructuredText Primer

reStructuredText is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents productively. Since reST was designed to be a simple, unobtrusive markup language, this will not take too long.

See also

The authoritative reStructuredText User Documentation . The “ref” links in this document link to the description of the individual constructs in the reST reference.

Paragraphs

The paragraph ( ref ) is the most basic block in a reST document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation.

Inline markup

The standard reST inline markup is quite simple: use

• one asterisk: *text* for emphasis (italics),

• two asterisks: **text** for strong emphasis (boldface), and

• backquotes: ``text`` for code samples.

If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.

Be aware of some restrictions of this markup:

• it may not be nested,

• content may not start or end with whitespace: * text* is wrong,

• it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis\ *one*\ word .

These restrictions may be lifted in future versions of the docutils.

It is also possible to replace or expand upon some of this inline markup with roles. Refer to Roles for more information.

Lists and Quote-like blocks

List markup ( ref ) is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be autonumbered using a # sign:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

• This is a bulleted list.

• It has two items, the second item uses two lines.

1. This is a numbered list.
2. It has two items too.

1. This is a numbered list.

2. It has two items too.

#. This is a numbered list.
#. It has two items too.

1. This is a numbered list.

2. It has two items too.

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

• this is

• a list

  • with a nested list

  • and some subitems

• and here the parent list continues

Definition lists ( ref ) are created as follows:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

term (up to a line of text)

Definition of the term, which must be indented

and can even consist of multiple paragraphs

next term

Description.

Note that the term cannot have more than one line of text.

Quoted paragraphs ( ref ) are created by just indenting them more than the surrounding paragraphs.

Line blocks ( ref ) are a way of preserving line breaks:

| These lines are
| broken exactly like in
| the source file.

These lines are

broken exactly like in

the source file.

There are also several more special blocks available:

• field lists ( ref , with caveats noted in Field Lists )

• option lists ( ref )

• quoted literal blocks ( ref )

• doctest blocks ( ref )

Literal blocks

Literal code blocks ( ref ) are introduced by ending a paragraph with the special marker :: . The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines):

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

This is a normal text paragraph. The next paragraph is a code sample:

It is not processed in any way, except
that the indentation is removed.

It can span multiple lines.

This is a normal text paragraph again.

The handling of the :: marker is smart:

• If it occurs as a paragraph of its own, that paragraph is completely left out of the document.

• If it is preceded by whitespace, the marker is removed.

• If it is preceded by non-whitespace, the marker is replaced by a single colon.

That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph is a code sample:”.

Code highlighting can be enabled for these literal blocks on a document-wide basis using the highlight directive and on a project-wide basis using the highlight_language configuration option. The code-block directive can be used to set highlighting on a block-by-block basis. These directives are discussed later.

Doctest blocks

Doctest blocks ( ref ) are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with with an unused prompt:

>>> 1 + 1
2

The doctest appears below,

>>> 1 + 1

Tables

For grid tables ( ref ), you have to “paint” the cell grid yourself. They look like this:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	…	…

Simple tables ( ref ) are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

Two more syntaxes are supported: CSV tables and List tables . They use an explicit markup block . Refer to table directives in the Sphinx documentation for more information.

Hyperlinks

External links

Use `Link text <https://domain.invalid/>`_ for inline web links. If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text.

Important

There must be a space between the link text and the opening < for the URL.

You can also separate the link and the target definition ( ref ), like this:

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

This is a paragraph that contains a link .

Internal links

Internal linking is done via a special reST role provided by Sphinx, see the section on specific markup.

Sections

Section headers ( ref ) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

=================
This is a heading
=================

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python’s Style Guide for documenting which you may follow:

• # with overline, for parts

• * with overline, for chapters

• = , for sections

• - , for subsections

• ^ , for subsubsections

• " , for paragraphs

Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.

Field Lists

Field lists ( ref ) are sequences of fields marked up like this:

:fieldname: Field content

They are commonly used in Python documentation:

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Sphinx extends standard docutils behavior and intercepts field lists specified at the beginning of documents. Refer to field lists in the Sphinx documentation for more information.

Roles

A role or “custom interpreted text role” ( ref ) is an inline piece of explicit markup. It signifies that that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is :rolename:`content` .

Docutils supports the following roles:

• emphasis – equivalent of *emphasis* ( emphasis )

• strong – equivalent of **strong** ( strong )

• literal – equivalent of ``literal`` ( literal )

• subscript – subscript text (subscript _subscript )

• superscript – superscript text (superscript ^superscript )

• title-reference – for titles of books, periodicals, and other materials

Refer to roles in the Sphinx documentation for roles added by Sphinx.

Explicit Markup

“Explicit markup” ( ref ) is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.

An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.)

Directives

A directive ( ref ) is a generic block of explicit markup. Along with roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it.

Docutils supports the following directives:

• Admonitions: attention , caution , danger , error , hint , important , note , tip , warning and the generic admonition . (Most themes style only “note” and “warning” specially.)

Attention

Attention

Caution

Caution

Danger

Danger

Error

Error

Hint

Hint

Important

Important

Note

Note

Tip

Tip

Warning

Warning

• Images:

  • image (see also Images below)

  • figure (an image with caption and optional legend)

• Additional body elements:

  • contents (a local, i.e. for the current file only, table of contents)

  • container (a container with a custom class, useful to generate an outer <div> in HTML)

  • rubric (a heading without relation to the document sectioning)

  • topic , sidebar (special highlighted body elements)

  • parsed-literal (literal block that supports inline markup)

  • epigraph (a block quote with optional attribution line)

  • highlights , pull-quote (block quotes with their own class attribute)

  • compound (a compound paragraph)

• Special tables:

  • table (a table with title)

  • csv-table (a table generated from comma-separated values)

  • list-table (a table generated from a list of lists)

• Special directives:

  • raw (include raw target-format markup)

  • include (include reStructuredText from another file) – in Sphinx, when given an absolute include file path, this directive takes it as relative to the source directory

  • class (assign a class attribute to the next element) 1

• HTML specifics:

  • meta (generation of HTML <meta> tags, see also HTML Metadata below)

  • title (override document title)

• Influencing markup:

  • default-role (set a new default role)

  • role (create a new role)

  Since these are only per-file, better use Sphinx’s facilities for setting the default_role .

Warning

Do not use the directives sectnum , header and footer .

Directives added by Sphinx are described in directives in the Sphinx documentation.

Basically, a directive consists of a name, arguments, options and content. (Keep this terminology in mind, it is used in the next chapter describing custom directives.) Looking at this example,

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

function is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option module (as you can see, options are given in the lines immediately following the arguments and indicated by the colons). Options must be indented to the same level as the directive content.

The directive content follows after a blank line and is indented relative to the directive start.

Images

reST supports an image directive ( ref ), used like so:

.. image:: gnu.png
   (options)

When used within Sphinx, the file name given (here gnu.png ) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png .

Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.)

Interpretation of image size options ( width and height ) is as follows: if the size has no unit or the unit is pixels, the given size will only be respected for output channels that support pixels. Other units (like pt for points) will be used for HTML and LaTeX output (the latter replaces pt by bp as this is the TeX unit such that 72bp=1in ).

Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:

.. image:: gnu.*

Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at Material for Sphinx .

Note that image file names should not contain spaces.

Changed in version 0.4: Added the support for file names ending in an asterisk.

Changed in version 0.6: Image paths can now be absolute.

Changed in version 1.5: latex target supports pixels (default is 96px=1in ).

Footnotes

For footnotes ( ref ), use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

You can also explicitly number the footnotes ( [1]_ ) or use auto-numbered footnotes without names ( [#]_ ).

Citations

Standard reST citations ( ref ) are supported, with the additional feature that they are “global”, i.e. all citations can be referenced from all files. Use them like so:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Citation usage is similar to footnote usage, but with a label that is not numeric or begins with # .

Here we take a look at some actual citations of famous papers such as [Chetty] in the American Economic Review or [Silver] in Nature.

Chetty

Chetty, Raj, Nathaniel Hendren, and Lawrence F. Katz. “The effects of exposure to better neighborhoods on children: New evidence from the Moving to Opportunity experiment.” American Economic Review 106.4 (2016): 855-902.

Silver

Silver, David, et al. “Mastering the game of Go with deep neural networks and tree search.” nature 529.7587 (2016): 484-489.

Substitutions

reST supports “substitutions” ( ref ), which are pieces of text and/or markup referred to in the text by |name| . They are defined like footnotes with explicit markup blocks, like this:

.. |name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
             :alt: Warning!

See the reST reference for substitutions for details.

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Sphinx defines some default substitutions.

Comments

Every explicit markup block which isn’t a valid markup construct (like the footnotes above) is regarded as a comment ( ref ). For example:

.. This is a comment.

You can indent text after a comment start to form multiline comments:

..
   This whole indented block
   is a comment.

   Still in the comment.

HTML Metadata

The meta directive ( ref ) allows specifying the HTML metadata element of a Sphinx documentation page. For example, the directive:

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

will generate the following HTML output:

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

Also, Sphinx will add the keywords as specified in the meta directive to the search index. Thereby, the lang attribute of the meta element is considered. For example, the directive:

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

adds the following words to the search indices of builds with different language configurations:

• pleasefindthiskey , pleasefindthiskeytoo to English builds;

• bittediesenkeyfinden to German builds;

• backup to builds in all languages.

Source encoding

Since the easiest way to include special characters like em dashes or copyright signs in reST is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the source_encoding config value.

Gotchas

There are some problems one commonly runs into while authoring reST documents:

• Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that. See the reference for the details.

• No nested inline markup: Something like *see :func:`foo`* is not possible.

Footnotes

1

When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class .

Titleless

This page does not have a title.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.

Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.

Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.

Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.

Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.

Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.

Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.

Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.

Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.

Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.

Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.

Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.

Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.

Change Log

Warning

Changes are not being tracked until a beta-quality release is made.

The change log will appear here.

License

Copyright (c) 2019 Kevin Sheppard < kevin . k . sheppard @ gmail . com >

Derived from:

• Material for Mkdocs: Copyright (c) 2016-2019 Martin Donath < martin . donath @ squidfunk . com >

• Guzzle Sphinx Theme: Copyright (c) 2013 Michael Dowling < mtdowling @ gmail . com >

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

Index