Table Of Contents

The Cloud Sphinx Theme

This is release 1.10.0 of a small Python package named cloud_sptheme. It contains a Sphinx theme named “Cloud”, and some related Sphinx extensions. Cloud and its extensions are primarily oriented towards generating html documentation for Python libraries. It provides numerous small enhancements to make the html documentation html more interactive, improve the layout on mobile devices, and other enhancements.

Contents

See also

What’s new in v1.9

Themes

Cloud Sphinx Theme
the main Sphinx theme provided by this package, and used by this documentation.

Markup Extensions

The following extensions make some helpful enhancements to sphinx’s markup. They should all be theme-independant.

cloud_sptheme.ext.autodoc_sections
Patches sphinx.ext.autodoc to handle RST section headers inside docstrings.
cloud_sptheme.ext.autoattribute_search_bases
Patches sphinx.ext.autodoc so that .. autoattribute:: will also search parent classes for attribute docstrings.
cloud_sptheme.ext.docfield_markup
Patches Sphinx to permit tilde-prefixed markup in directives, such as :raises ~myapp.MyException:
cloud_sptheme.ext.escaped_samp_literals
Patches Sphinx to permit backslash-escaped {} characters within :samp: roles.
cloud_sptheme.ext.issue_tracker
Adds a special :issue: role for quickly linking to your project’s issue tracker.
cloud_sptheme.ext.table_styling
Enhances .. table directive to support per-column text alignment and other layout features.

Meta Extensions

The following extensions add some additional capabilities and features for building sphinx documentation. They should all be theme-independant.

cloud_sptheme.ext.auto_redirect
Helper to alert users when documentation hosting has moved to a different url.
cloud_sptheme.ext.page_only
Directive that allows entire pages to be conditionally omitted from a build, similar to .. only::.
cloud_sptheme.ext.relbar_links
Adds a TOC or other custom links to the top navigation controls.
cloud_sptheme.ext.role_index
Generates a “roleindex.json” of all document and cross-references, to help integrate sphinx documentation into a web application’s context-aware help.

Theme-Specific Extensions

The following Sphinx extensions provide features used by the Cloud theme, and may prove useful for documentation that needs a specific feature:

cloud_sptheme.ext.index_styling
Adds additional css styling classes to the index page.

Reference

Installation Instructions
requirements and installations instructions
Release History
history of current and past releases

Installation Instructions

Requirements

  • Python >= 2.6 or Python 3
  • Sphinx 1.4 or newer.

Installing

  • To install from pypi using pip:

    pip install cloud_sptheme

  • To install from pypi using easy_install:

    easy_install cloud_sptheme

  • To install from source using setup.py:

    python setup.py build
sudo python setup.py install

ReadTheDocs

To use this theme on https://readthedocs.org:

  1. If it doesn’t already exist, add a pip requirements.txt file to your documentation (e.g. alongside conf.py). It should contain a minimum of the following lines:

    sphinx
cloud_sptheme

    … as well as any other build requirements for your project’s documentation.

  2. When setting up your project on ReadTheDocs, enter the path to requirements.txt in the requirements file field on the project configuration page.

  3. ReadTheDocs will now automatically download the latest version of cloud_sptheme when building your documentation.

Documentation

The latest copy of this documentation should always be available at:
https://cloud-sptheme.readthedocs.io

If you wish to generate your own copy of the documentation, you will need to:

  1. Install Sphinx (1.4 or better)
  2. Download the cloud_sptheme source.
  3. From the source directory, run python setup.py build_sphinx -E.
  4. Once Sphinx is finished, point a web browser to the file SOURCE/build/sphinx/html/index.html.

“Cloud” sphinx theme

Features

This package provides a theme called “Cloud”, used to generate this documentation. Aside from being just another Sphinx theme, it has a few special features:

Toggleable sections
You can mark sections with .. rst-class:: html-toggle, which will make the section default to being collapsed under html, with a “show section” toggle link to the right of the title.
Additional CSS classes

It provides a couple of simple styling directives for adding variety to long Python library documentation:

  • You can mark tables with .. rst-class:: html-plain-table to remove separating lines between rows.
  • You can mark <h2> sections with .. rst-class:: emphasize-children to provide addition visual dividers between large numbers of sub-sub-sections.
Navigation enhancements
It provides options (roottarget, logotarget) which allow the table of contents to be a distinct from the front page (index.html) of the document. This allows a master table of contents to be maintained, while still allowing the front page to be fully customized to welcome readers.
Additional styling options

It also provides a number of styling options controlling small details such as external links, document sizing, etc. See below.

It also uses an adaptive layout to work well on all screen sizes from mobile phones to widescreen desktops.

Google Analytics Integration
By enabling two theme options with conf.py, Cloud will automatically insert a Google Analytics tracker to the bottom of each page, along with a polite link allowing users to set a cookie which opts them out.

List of Options

Structure

roottarget
Sets the page which the title link in the navigation bar should point to (defaults to the special value "<toc>", which uses the table of contents).
logotarget
Sets the page which the sidebar logo (if any) should point to (defaults to the special value <root>, which just mirrors roottarget).

Document Layout

max_width
Sets the maximum document width, so the documentation does not stretch too far on wide monitors (defaults to 11in).
minimal_width
Sets the maximum width where the “mobile” layout will be used. This layout omits the sidebar and everything else that can be trimmed, and is designed to (hopefully) be more usuable on mobile devices. (defaults to 700px).
min_height
sets the minimum height of the page body (defaults to 6in).

Changed in version 1.7: compact_width option has been removed, and will be ignored. (it previously provided an intermediate level of padding between minimal_width and max_width).

Font Sizing

default_layout_text_size

Sets the default font size for the whole document (defaults to 87.5% of browser default).

minimal_layout_text_size

Sets the default font size for the whole document when the “mobile” layout is being used (defaults to 75% of browser default).

Document Styling

lighter_header_decor
Optional boolean flag which render headers in a lighter underlined style, rather than with a solid background. Also enables other related stylistic changes.
shaded_decor
Optional boolean flag which adds a slight amount of shading to sidebar, navbars, and section headers.
borderless_decor
Optional boolean flag which makes page background match document background. Also enables other related stylistic changes.

Styling

externalrefs
Boolean flag that controls whether references should be displayed with an icon. (defaults to True).
externalicon
Optional image or string to prefix before any external links (defaults to ⇗, ignored if externalrefs=False).
issueicon
Optional image or string to prefix before any issue tracker links generated by cloud_sptheme.ext.issue_tracker (defaults to ✧, ignored if externalrefs=False).

Note

There are a number of options for changing the various colors and fonts used by this theme, which are still undocumented. A complete list can be found in the theme’s configuration file (/cloud_sptheme/themes/cloud/theme.conf).

Other

googleanalytics_id
Setting this via html_theme_options to your GA id (e.g. UA-XXXXXXXX-X) will enable a Google Analytics tracker for all pages in the document, as well insert a link in the footer allowing users to opt out of tracking.
googleanalytics_path
Setting this allows limiting the tracker to a subpath, useful for shared documentation hosting (e.g. PyPI or ReadTheDocs).

Usage

Using the theme

To use the cloud theme, make sure this package is installed properly, then open your documentation’s Sphinx conf.py file, and make the following changes:

# set the html theme
html_theme = "cloud"
    # NOTE: there are also alternate versions named "redcloud" and "greencloud"

# ... some contents omitted ...

# [optional] set some of the options listed above...
html_theme_options = { "roottarget": "index" }

See also

See the next page (Feature Test) for examples of these options in action.

Section Styles

Emphasized Children

Adding .. rst-class:: emphasize-children to a 2nd-level section header will cause the headers of all of it’s child sections to be emphasized with a solid background. This is mainly useful for very long sections, where there needs to be a visual divide between 3rd-level sections.

Toggleable Sections

By adding .. rst-class:: html-toggle before any section header, it can be made toggleable:

.. rst-class:: html-toggle

Toggleable Section
------------------

This section is collapsed by default.

While toggleable sections start out collapsed by default, you can use .. rst-class:: html-toggle expanded to override this.

Table Styles

  • Adding .. rst-class:: plain can be used to remove the row shading and other styling from a table.

  • Adding .. rst-class:: centered can be used to center a table.

    Deprecated since version 1.10.0,: use docutils’ :align: center directive instead.

  • Adding .. rst-class:: fullwidth can be used to expand a table to the full width of the page.

See also

The table_styling extension for additional table styling abilities, e.g. per-column text alignment.

API Reference

The reference section contains documentation of Cloud’s Sphinx extensions and utility functions.

Module list:

cloud_sptheme - helper functions

The main cloud_sptheme module contains the following helper functions:

cloud_sptheme.get_theme_dir()[source]

Returns path to directory containing this package’s Sphinx themes.

Deprecated since version 1.7: As of Sphinx 1.2, this is passed to Sphinx via a setup.py entry point, and no longer needs to be included in your documentation’s conf.py.

cloud_sptheme.get_version(release)[source]

Derive short version string from longer ‘release’ string.

This is quick helper which takes a project’s release string, and generates the shortened version string required by conf.py. Usage example for conf.py:

import cloud_sptheme as csp

...

# The version info for the project you're documenting
from myapp import __version__ as release
version = csp.get_version(release)

cloud_sptheme.ext.index_styling - improves css styling for genindex

Overview

This Sphinx extension intercepts & modifies the general index data before it is rendered to html, adding some additional css classes to help Sphinx themes (e.g. “Cloud” sphinx theme) provide additional per-type styling for index entries.

Internals

This extension adds the following css classes to genindex.html:

  • For all entries referencing an attribute, method, class, function, or module:
    • The text containing the type of the entry (e.g. attribute or method) is wrapped in a <span class="category type">...</span> tag.
    • If the entry contains a location (e.g. myclass in module myapp), the myapp portion is wrapped in a <span class="location">...</span> tag.
  • Entries which don’t fit into one of the above categories are not modified.

cloud_sptheme.ext.relbar_toc - adds TOC entry to relbar

Deprecated since version 1.8.1: This extension is now an alias for cloud_sptheme.ext.relbar_links. This alias will be removed at some point in the future.

cloud_sptheme.ext.autodoc_sections - support for ReST sections in docstrings

Changed in version 1.7: Drastically revamped how extension works, as well as the DOM / css styles it generates. Themes relying on the previous output structure may need to be updated (the css classes were changed, to allow simulatenous styling of both old and new versions).

Overview

This Sphinx extension should be used in conjunction with the Autodoc extension. This extension allows docstrings (module, class, function, etc) to include ReST-style section headers (which normally cause problems if integrated into Sphinx documentation via Autodoc).

Internals

This extension does an extensive amount of monkeypatching within Sphinx and Docutils. While this allows it to leverage Docutil’s native RST parser (rather than implement it’s own), this does mean it may be more fragile if any of the internals change. Please report any bugs.

In order for Sphinx themes (like this one) to distinguish document-level sections from the special object-description sections generated by this extension, it assigns two extra css classes to the sections it generates: desc-section and desc-section-level. Additionally, the header element of each section is assigned the css class section-header. Depending on the theme, these may require additional styling rules.

Todo

This extension has a few things which could be improved:

  • Subsections should be included in Sphinx’s indexing.

cloud_sptheme.ext.autoattribute_search_bases

New in version 1.7.

Overview

Currently, sphinx.ext.autodoc’s autoattribute only checks the current class for an attribute docstring. This extension patches Sphinx so that if one isn’t found, autodoc will then search through the parent classes, in case the attribute is defined there, but is being documented in the subclass.

cloud_sptheme.ext.docfield_markup - support ~mod.class markup in docfields

New in version 1.7.

Overview

Currently, Sphinx docfields only allow full type references (e.g. :raises myapp.MyException:). This extension monkeypatches Sphinx so that tilde prefixes can be used (e.g. :raises ~myapp.MyException:), resulting in a proper crosslink with only the final class name being displayed (ala the various reference roles).

cloud_sptheme.ext.issue_tracker - support for issue text role

Overview

This Sphinx extension adds a new text role, :issue:, which will automatically be converted into links to your project’s issue tracker.

Issue roles should have the format :issue:`5` or :issue:`Custom Title <5>`. They will be converted into external references to the appropriate issue number in your project’s issue tracker.

Configuration

This extension reads the following conf.py options:

issue_tracker_url

This should provide a path to the project’s issue tracker. It should have one of the following formats:

  • bb:user/project – link to BitBucket issue tracker for specified project
  • gh:user/project – link to GitHub issue tracker for specified project
  • string containing arbitrary url, the substring {issue} will be replaced with the relevant issue number, and {title} with the link title.

If this option is not specified, all issue references will be converted into labels instead of links.

issue_tracker_title

Template for generating default title for references that only specify the issue number (e.g. :issue:`5`). This defaults to Issue {issue}.

conf.py Usage Example:

# add to list of extensions:
extensions = [
    ...
    'cloud_sptheme.ext.issue_tracker',
]

...

# set path to issue tracker:
issue_tracker_url = "https://example.org/tracker/{issue}"

Internals

Note

For themeing purposes, the generated <a> tag will have an issue CSS class added to it.

Changed in version 1.8.4: Removed “Google Code” preset url format.

cloud_sptheme.ext.escaped_samp_literals - permits escaped bracket characters in samp role

Overview

This extension modifies how :samp: literals are parsed, replacing the default Sphinx parser with an alternate one that allows embedding literal { and } characters within the content, as well providing stricter input validation.

To embed a literal {, just use a double-backslash, e.g:

:samp:`this is a {variable}, these are a literal \\{ and \\}`

… and it will be rendered as:

this is a variable, these are a literal { and }

Internals

See also

This feature has been submitted to Sphinx as issue 789. If/when that issue is resolved, this extension will be deprecated and removed.

cloud_sptheme.ext.page_only – Exclude Pages from Build

New in version 1.8.

Overview

This extension provides a .. page-only:: directive, which allows conditionally omitting entire pages from the document based on build tags.

The first line of a page should be a .. page-only:: <expr> directive; where <expr> is a tag, or simple tag expression, just like .. only::. If the expression evaluates to False, the page won’t be included in the final build (and should be silently omitted from any TOC lists).

E.g. .. page-only:: draft and html

cloud_sptheme.ext.role_index – JSON Role Index

New in version 1.8.

Overview

This sphinx extension for the HTML builder places a file called roleindex.json in the output directory along with the documentation. This file contains a dictionary which mapping all reference ids (made via :ref: or :doc:) to a 3-element list of (page, anchor, title)

This is useful for integrating a Sphinx manual into the online help of web application – context-specific help can be provided by looking up a predefined :ref: tag within the json file, and redirecting the user to the appropriate page and anchor location.

As an example, see the roleindex.json for this documentation.

Warning

This extension should be considered “beta” quality. It was recently written, may have unknown issues, and may need to be revised.

Configuration

This extension reads the following conf.py options:

role_index_style

style of json output – can be "compact" (the default), or "pretty" (for debugging).

cloud_sptheme.ext.table_styling - adds directives for styling tables

Changed in version 1.9: Added :header-alignment: directive.

Overview

This Sphinx extension replaces the default .. table:: directive with a custom one, that supports a number of extra options for controlling table layout on a per-column basis.

For example, the following snippet specifies relative widths for the three columns, changes the text alignment for each column, disables text-wrapping for the third column, and inserts dividers between the columns:

.. table:: Optional Caption
    :widths: 3 2 1
    :column-alignment: left center right
    :column-wrapping: true true false
    :column-dividers: none single double single

    =========== =========== ===========
    Width 50%   Width 33%   Width 16%
    =========== =========== ===========
    Line 1      This text   This text
                should wrap will always
                onto        be one line.
                multiple
                lines.
    Line 2      Centered.   Right-Aligned.
    Line 3      Centered    Right-Aligned
                Again.      Again.
    =========== =========== ===========

This will then result in the following table:

Optional Caption
Width 50% Width 33% Width 16%
Line 1 This text should wrap onto multiple lines. This text will always be one line.
Line 2 Centered. Right-Aligned.
Line 3 Centered Again. Right-Aligned Again.

Directive Options

The enhanced .. table:: directive supports the following options:

:widths:

Sets proportional column widths

This should be a space-separated list of positive integers, one for every column. The columns widths will be allocated proportionally (e.g. 1 2 3 for a 3-column table means the columns will use 16%, 33%, and 50% of the total width, respectively).

:column-alignment:

Sets per-column text alignment

This should be a comma/space-separated list of the following strings: left, right, center, justify. These are interpreted one per column. Extra values are ignored; if not enough values are provided, the remaining columns will default to left.

Alternately this can be a single word containing just the first letters: e.g. lrcj would be interpreted the same as left right center justify.

:header-alignment:

Sets per-column text alignment for header rows.

This has the same format as :column-alignment:. If specified, all headers rows will use these alignment values instead of the default column alignments.

:column-wrapping:

Sets per-column text wrapping

This should be a comma/space-separated list of either yes/true or no/false. If yes (the default), words will wrap around if there is not enough horizontal space. If no, whitespace-wrapping will be disabled for that column. Extra values are ignored; if not enough values are provided, the remaining columns will default to true.

Alternately this can be a single word containing just the first letters: e.g. ttf is the same as true true false.

:column-dividers:

Add dividers between columns

This lets you specify custom vertical dividers between columns (ala what .. tabularcolumns:: allows under latex).

This should be a comma/space-separated list of none, single, or double; based on the type of divider you want. There should be one of these for the left side of the table, for between each column, and for the right side of the table (e.g. a 4 entries for a 3-column table). Extra values are ignored; if not enough values are provided, the remaining columns will default to none.

Alternately this can be a single word containing just the number: e.g. 0121 is the same as none single double single.

:column-classes:

Add per-column css classes.

This lets you specify css classes that will be assigned to each column, much like .. rst-class::. This should either be a space-separated list containing one class per column, or a comma-separated list containing multiple classes for each column, separated by spaces. Extra values are ignored; if there are not enough values, or there are blank entries, those columns will not be assigned any custom classes.

For example, a b, c , , d would assign the classes a b to column 1, c to column 2, no custom classes for column 3, and d to column 4.

:header-columns:

Specify number of “stub” columns

Should be a non-negative integer specifying the number of columns (starting with the left side) that should be treated as “stub” or “header” columns, and should be styled accordingly.

Configuration

This extension reads the following conf.py options:

table_style_default_align

Optionally add default value for :align: directive. Sphinx 2 changed it’s default to “centered” tables, setting this directive to “left” will restore the original behavior.

New in version 1.10.0.

table_styling_embed_css

Controls whether or not the custom css file should be included. Defaults to True, set to False to disable.

table_styling_class

By default, all HTML tables styled by this extension will have the css class "styled-table" added, to help with themeing support. Use this option to override with your own theme’s preferred css class.

Internals

Note

This extension gets the job done by adding custom css classes to every cell in the generated html table. It then inserts a custom css file which provides styling implementing relevant parts of the above directives. While this extension is primarily tested with cloud_sptheme, it should work with most Sphinx themes, any conflicts that occur are probably bugs.

Todo

make this autogenerate a matching .. tabularcolumns directive for latex.

Todo

allow :widths: to support em, in, %

cloud_sptheme.ext.auto_redirect – Redirect Deprecated URLs

New in version 1.9.

Overview

This extension is helpful for when html documentation has been relocated to a new host; e.g. moving from pythonhosted.org to readthedocs.io. Once enabled, it adds a helpful “Documentation has moved” message to the top of every page, and automatically redirects the user as well.

Configuration

This extension looks for the following config options:

auto_redirect_subject

subject to insert into message. defaults to The {project name} documentation.

auto_redirect_domain_url

url to redirect user to. no message or redirect will happen if this isn’t set.

auto_redirect_domain_footer

optional footer text to append to message

Internals

This should work with other sphinx themes, the js & css is (mostly) generic.

Todo

the “redirect to exact page” part of JS code currently only works with this theme; would like to fix that.

Todo

support configuring redirects to other pages within same documentation.

Todo

if user has dismissed “auto redirect”, remember via cookie?

Feature Test

This page contains examples of various features of the Cloud theme. It’s mainly useful internally, to make sure everything is displaying correctly.

Inline Text

Inline literal: literal text.

Samp literal: this is a variable, these are literal { and }.

External links are prefixed with an arrow: http://www.google.com.

But email links are not prefixed: bob@example.com.

Issue tracker link: issue 5.

This text should be crossed out

Admonition Styles

Note

This is a note.

Caution

This is a slightly dangerous.

Warning

This is a warning.

Danger

This is dangerous.

See also

This is a “see also” message.

Todo

This is a todo message.

With some additional next on another line.

Deprecated since version XXX: This is a deprecation warning.

New in version XXX: This was added

Changed in version XXX: This was changed

Note

This is note using the float-right class.

Note

This is note using the float-center class.

See also

This is a “see also” using the without-title class.

Code Styles

Python Code Block:

1
2
3
4
5
6
7
8
9
>>> import os

>>> os.listdir("/home")
['bread', 'pudding']

>>> os.listdir("/root")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: [Errno 13] Permission denied: '/root'

INI Code Block:

1
2
3
4
[rueben]
bread = rye
meat = corned beef
veg = sauerkraut

Long Lines (issue 22):

1
2
3
4
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ


0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

Function styling:

frobfunc(foo=1, *, bar=False)
Parameters:
  • foo (int) – foobinate strength
  • bar (bool) – enabled barring.
Returns:

frobbed return
Return type:

str
Raises:

TypeError – if foo is out of range

Class styling:

class FrobClass(foo=1, *, bar=False)

Class docstring. Saying things.

foo

foobinate strength

bar

barring enabled

run()

execute action, return result.

Table Styles

Default Table
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3
Plain Table (no row shading)
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3
Left Table
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3
Center Table
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3
Right Table
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3
Full Width Table
Header1 Header2 Header3
Row 1 Row 1 Row 1
Row 2 Row 2 Row 2
Row 3 Row 3 Row 3

Table Styling Extension

Column Separators
Width x1 Width x2 Width x3
Header 1 Center 1 Right 1
Header 2 Center 2 Right 2
Header 3 Center 3 Right 3
Header Alignment & Body Colspans
Left x1 Right x1 Left x1 Right x1 Left x2 Right x2 Left x4 Right x4
Left Span x1+1 Center Span x1+1+2+2 Center Span x4+4
Left Span xALL
Left Span xALL
Multi-Row Header & Header Colspans
Left x1 Right x1 Left x1 Right x1 Left x2 Right x2 Left x4 Right x4
Left Span x1+1 Center Span x1+1+2+2 Center Span x4+4
H x1 x1 Center Span x1+1 Center Span x2+2 Center Span x4+4
H x1 Center Span xALL

Toggleable Section

This section is collapsed by default. But if a visitor follows a link to this section or something within it (such as this), it will automatically be expanded.

Toggleable Subsection

Subsections can also be marked as toggleable. This one should be expanded by default.

Normal Section

Child Section

Toggleable Subsection

Test of emphasized + toggleable styles. Should be collapsed by default.

Section With Emphasized Children

Mainly useful for sections with many long subsections, where a second level of visual dividers would be useful.

Child Section

Should have slightly lighter background, and be indented.

Toggleable Subsection

Test of emphasized + toggleable styles. Should be collapsed by default.

autodoc_sections Extension

cloud_sptheme.ext.autodoc_sections._doctestfunc()[source]

The autodoc_sections extension should generate nested sections as found within object docstrings.

Nested Section

Parameters:arg – xxx
cloud_sptheme.ext.autodoc_sections.foo

bar

These sections can in turn contain others:

Child Section

Which allows breaking long class docstrings up in meaningful ways.

Child Section 2

And more content

Nested Section 2

end of class

Release History

1.10.0 (2019-11-22)

Note

This package now requires Sphinx >= 1.6, and should be compatible with Sphinx 2.x

Other Changes

  • table_styling: Now supports table_styling_default_align config option, for setting the default table alignment (Sphinx 2 switched from "left" to "center").
  • theme css: Minor style adjustments

Bugfixes

  • role_index: fix AttributeError under Sphinx 1.7+ (issue 38)
  • setup.py: updated entrypoints to work with Sphinx 1.7+ (issue 39)
  • theme css: layout fix for “sphinx.ext.viewcode” (issue 37)
  • theme css & js: fixes Sphinx 1.6 - 2.2 compatibility (issue 42 and other corrections).
  • table_styling: now plays nicely with docutils table :align: directive.

1.9.4 (2017-04-05)

  • auto_redirect:

    • simplified markup
    • skip popup if referrer is within document
    • bugfix: correctly handle source document that’s not at root of url

  • bugfix: docfield_markup: sphinx 1.5 compat fix

  • bugfix: table_styling: header-alignment not being parsed correctly

1.9 (2017-04-02)

New Features

  • Added auto_redirect extension, to help alert users when documentation location has changed.
  • table_styling now handles colspans correctly, and supports new :header-alignment: directive for setting separate alignment on header columns (issue 28, issue 29, and issue 33).

Other Changes

Bugfixes

  • bugfix: js code updated to be compatible with jquery 3
  • bugfix: page_only no longer chokes on non-ascii chars in page
  • bugfix: table_styling should no longer cause “directive already exists” warning under sphinx 1.5 (issue 32).

1.8.3 (2017-2-8)

Bugfix release

  • bugfix: relbar_links: fixed potential label/title mixup, added some unittests.
  • bugfix: Setup script should no longer append timestamp when building from sdist; which should fix some reproducible-build issues downstream.
  • Added tox.ini script, with some very minimal tests.
  • Updated documentation.

1.8.2 (2017-1-30)

Bugfix release

  • bugfix: relbar_links: resolve translation proxies to prevent hash() error

1.8.1 (2017-1-30)

Bugfixes, and new “relbar_links” extension added:

  • relbar_toc extension deprecreated, replaced with more flexible relbar_links extension. This should also fix issues with broken links under ‘dirhtml’ and other builders.
  • Assorted internal fixes to CSS template.
  • Documentation layout updated.

1.8 (2016-11-20)

Note

This theme now requires Sphinx >= 1.4

New Features

  • Admonitions now support “without-title” class to hide title prefix (“Note”, “See also”, etc)
  • Added role_index extension
  • Added page_only extension

Other Changes

  • Sticky sidebar code now allows sidebar to be scrolled independently of main document – just scroll mouse while overing over sidebar.
  • Sidebar can now be viewed from mobile mode; hidden state is stored independently of large screen menu.
  • A large amount of the sidebar css & js was rewritten, many of the DOM classes have changed.

Deprecations

  • collapsablesidebar flag is now ignored, sidebar is always collapsable. flag will be removed in 1.9.

Bugfixes

1.7.1 (2015-12-12)

Bugfix release

  • Fixed divide-by-zero error under python 3 (issue 23).
  • JS url comparison code now handles file:// urls (issue 24).
  • Now requires Sphinx >= 1.3.

1.7 (2015-07-25)

Note

This theme now requires Sphinx >= 1.2 (some of the javascript code won’t work with the jquery version bundled in Sphinx 1.1 and earlier).

New Features

Other Changes

  • autodoc_sections has been completely rewritten. now utilitizes docutil’s native RST parser, creates real section elements rather than hacked up definition lists; should now handle any valid rest directive that can be put at module-level.
  • Added styling for 2nd-level section headers, and the nested section headers generated by autodoc_sections.
  • Default font size adjusted for compactness.
  • The popuptoc feature has been removed. It was just too awkward to maintain the required styling. May revisit in the future using a JS-based approach.
  • Unified button hover look & color through relbar, sidebar, and body.
  • Completely rewrote TOC highlighter code, now indicates active section, and collapses inactive TOC entries that are too large.
  • Makes use of Sphinx 1.2’s egg entry point, so get_theme_dir() no longer needs to be used directly.

Bugfixes

  • autodoc_sections now monkeypatches sphinx so that :param foo: and other fields get formatted correctly when they’re embedded in a nested section (issue 21).
  • now compatibile with Sphinx 1.3’s switch from <tt> to <code> for literals.
  • autodoc_sections now monkeypatches sphinx so that :param foo: and other fields get formatted correctly when they’re embedded in a nested section (issue 21).
  • autodoc_sections now handles method descriptors correctly (issue 16).
  • the sidebar collapse state is now consistent across subfolders of document (issue 9).
  • jumping to method or attribute permalink will now highlight the object.

1.6 (2013-12-28)

New Features

  • Added rightsidebar option to base theme, ala the Sphinx default theme.
  • TOC entries which overflow sidebar now popup when hovered over (can be disabled via popuptoc = false).
  • Added sidebar_localtoc_title and a number of other options for changing the titles of various links in the sidebar.
  • Added a sidebar called quicklinks.html, which mirrors the navbar at the top and bottom of the page.
  • Various other small styling changes.

Bugfixes

  • Web font url now works with HTTPS
  • TOC highlighter now works with global toc (issue 7)

1.5 (2012-10-01)

New Features

  • Added plain, centered, and fullwidth css classes for positioning tables (see the theme options).
  • Added new extension cloud_sptheme.ext.table_styling, which adds some per-column styling options to the .. table:: directive.

Other Changes

  • Changed default font to Open Sans, for readability.
  • Removed all hardcoded pt or px font sizes, all sizes now specified as % of browser default.
  • Various improvements to mobile layout, including use of “viewport” metatag.

Bugfixes

  • Now compatible with jquery 1.8 (and thus sphinx 1.2)
  • Sticky sidebar code now more intelligent about various border cases.
  • Sticky sidebar now works when logo not present (issue 5)
  • Sidebar toggle and headers now displayed correctly when printed (issue 4)

1.4 (2012-08-02)

  • Sidebar now collapsible by default (issue 3).
  • Sidebar now “sticks” to window when scrolling.
  • Sidebar TOC now highlights sections currently being shown in window.
  • Numerous documentation updates.
  • Various minor bugfixes.
  • Now natively compatible with Python 3, the 2to3 command is no longer required.

1.3 (2012-05-01)

  • Cleaned up documentation.

  • Redid css layouts. Cloud now has three layouts, controlled by css media queries:

    • “Normal” mode displays the document as a center-aligned box within the browser window. It will not grow to be larger than max_width (default 11 inches) in size. (This theme parameter was previously named docwidth).
    • “Compact” mode strips the body padding to fill the whole window, but otherwise looks “Normal” mode. It will be used when the browser is less than compact_width (default 960 pixels) in size. This layout is new in 1.3.
    • “Minimal” mode strips excess padding, hides the sidebar, and does other things to reduce it’s footprint as much as possible. This mode will be used if the browser is less than minimal_width in size (currently 700px), or if it uses the "handheld" css media type. (This theme parameter was previously named smallwidth).

  • Added issue_tracker extension, for auto-creating links to a project’s issue tracker.

  • Added escaped_samp_literals extension, which patches Sphinx to allow literal { characters in samp roles.

  • Added optional Google Analytics integration.

  • Added collapsiblesidebar option, as well as defaultcollapsed option. Though sidebar is still always hidden under minimal mode.

  • Added a number of other rst-class styling directives.

1.2 (2011-07-11)

Minor stylistic changes to theme:

  • Changed section headers have colored background.
  • Added icons to admonitions.
  • Changed default font.
  • Other minor changes.

1.1 (2011-05-04)

New features:

  • CSS media query automatically hides sidebar & trim for small displays (e.g. mobile devices)
  • Toggleable sections javascript code rewritten, now auto-expands based on url hash.
  • The parser used by the autodoc_sections extension is now much more robust, and relies on fewer assumptions about the source.
  • Fixed header margin glitch that was occurring under Chrome.
  • Various minor layout enhancements.

1.0 (2011-03-25)

First public release.