Sphinx Readable Theme

A clean and readable Sphinx theme with focus on autodoc – documentation from docstrings.

Inspired by flask-sphinx-themes.

Installation and setup

Install from PyPI:

$ pip install sphinx-readable-theme

And add this to your conf.py:

import sphinx_readable_theme

html_theme_path = [sphinx_readable_theme.get_html_theme_path()]
html_theme = 'readable'

License

Sphinx Readable Theme is licensed under the MIT license.

Changelog

Version 1.1.0

  • Fixed footnote tables width – thanks, Nick Zaccardi!

Version 1.0.0

  • Fixed continuation lines in long ordered and unordered list items
  • Fixed references in Autodoc example

Version 0.1.0

First release

Theme style

Headings

H1: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

H2: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

H3: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

H4: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

H5: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

H6: Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Paragraphs

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum [1] dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat [2] non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Tables

Header row, column 1 Header row, column 2
body row 1 Second column of row 1
body row 2

Second column of row 2

Second line of paragraph

body row 3

Unordered list:

  • Second column of row 3
  • Second item in bullet list (row 3, column 2)
Row 4; column 1 will be empty

Lists

Unordered list

  • Lorem ipsum
  • Dolor sit amet
    • Dolor
    • Sit
    • Amet
  • Consectetur adipiscing elit

Ordered list

  1. Lorem ipsum
  2. Dolor sit amet
    1. Dolor
    2. Sit
    3. Amet
  3. Consectetur adipiscing elit

Definition Lists

Lorem
Lorem ipsum dolor sit amet.
Ipsum
Ipsum dolor amet sit.
Dolor : classifier
Dolor lorem ipsum.
Sit amet : classifier one : classifier two
Sit amet consectetur adipiscing elit.

Topics

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Admonitions

Admonition title

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Attention

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Caution

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Danger

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Error

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Hint

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Important

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Note

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

See also

Module zipfile
Documentation of the zipfile standard module.
GNU tar manual, Basic Tar Format
Documentation for tar archive files, including GNU tar extensions.

Tip

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Warning

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Code

"""An example module docstring to show Pygments style."""

# Some comment.

import datetime
from functools import partial

number = 123
word = 'foo'


class ExampleClass(object):

    """An example class docstring to show Pygments style."""

    def __init__(self, arg1, arg2=None, *args, **kwargs):
        self.attr1 = attr1
        self.attr2 = attr2 or datetime.datetime.now()
        for arg in args:
            print('Argument: '.format(arg))
        for k, v in kwargs.iteritems():
            print('Keyword argument named {}: {}'.format(k, v))

    def call_method(self, arg):
        """An example method docstring."""
        if not isinstance(arg, int):
            raise ValueError('Only ints allowed.')
        self.attr1 = arg

    @property
    def example_property(self):
        """An example property docstring."""
        return self.attr1 * 2


def example_function(arg1, arg2=None, *args, **kwargs):
    """An example function docstring to show Pygments style."""
    raise NotImplementedError()

Autodoc

An example module to show autodoc style.

Contains an example constant, Storage class for storing objects and helper function store_integers() for storing only integers.

INT_CONSTANT = 1

Example integer constant.

STR_CONSTANT = 'string'

Example integer constant.

class Storage(items=None)[source]

Bases: object

A class for storing objects.

This is an example class to show autodoc style.

It stores a list of objects and saves date of last appended item. Example usage:

>>> storage = Storage(['foo', 'bar'])
>>> storage.items
['foo', 'bar']
>>> storage.last_updated
datetime.datetime(2013, 8, 15, 13, 41, 38, 515797)
>>> storage.add_item('baz')
>>> storage.items
['foo', 'bar', 'baz']
>>> storage.last_updated
datetime.datetime(2013, 8, 15, 13, 41, 40, 595544)
Parameters:items – Optional list of items to start with.
items = None

List of items, add new item using add_item().

last_updated = None

datetime.datetime of last item update, will be set to datetime.datetime.now() on object instantiation.

add_item(item)[source]

Append item to the list.

last_updated will be set to datetime.datetime.now().

Parameters:item – Something to append to items.
store_integers(items, allow_zero=True)[source]

Store integers from the given list in a storage.

This is an example function to show autodoc style.

Return Storage instance with integers from the given list.

Examples:

>>> storage = store_integers([1, 'foo', 2, 'bar', 0])
>>> storage.items
[1, 2, 0]
>>> storage = store_integers([1, 'foo', 2, 'bar', 0], allow_zero=False)
>>> storage.items
[1, 2]
Parameters:
  • items – List of objects of any type, only int instances will be stored.
  • allow_zero – Boolean – if False, 0 integers will be skipped. Defaults to True.