Table Of Contents

The Cloud Sphinx Theme

This is release 1.8.3 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.8

Themes

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

Extensions

The following Sphinx extensions provide features used by the Cloud theme, and should be enabled for most documentation that uses it:

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

Generic Extensions

This package also provides a few extra Sphinx extensions which may be useful when documenting Python projects; and should be theme-agnostic:

cloud_sptheme.ext.autodoc_sections
Patches the 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-prefixes markup such as :raises ~myapp.MyException:
cloud_sptheme.ext.escaped_samp_literals
Patches Sphinx to permit escaped {} characters within a :samp: role.
cloud_sptheme.ext.issue_tracker
Adds a special :issue: role for quickly linking to your project’s issue tracker.
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.
cloud_sptheme.ext.table_styling
Enhances .. table directive to support per-column text alignment and other layout features.

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 http://readthedocs.org:

  1. If it doesn’t already exist, add a pip requirments.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:
http://packages.python.org/cloud_sptheme

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 which 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, open your documentation’s Sphinx conf.py file, make the following changes:

# import Cloud
import cloud_sptheme as csp

# ... some contents omitted ...

# set the html theme
html_theme = "cloud"
    # NOTE: there is also a red-colored version named "redcloud"

# ... some contents omitted ...

# set the theme path to point to cloud's theme data
html_theme_path = [csp.get_theme_dir()]

# [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.
  • 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()

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)

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.relbar_links - adds TOC entry to relbar

New in version 1.8.1.

Overview

This Sphinx extension allows you to insert links into the navigation bar (“relbar”) at the top of bottom of all pages.

While it can be configured with arbitrary links, by default it automatically inserts a Table Of Contents entry, similar to the old python documentation format. This is mainly useful when the title link in the navigation bar has been redirected to page other than Table Of Contents (such as allowed by the roottarget option of the “Cloud” sphinx theme).

Configuration

By default, this inserts a “TOC” link to the right of any “Next” or “Previous” buttons, which points to your sphinx master document.

It can be customized using the following options in conf.py:

relbar_links

Optional list of links to insert, defaults to ["toc"]. They can have one of four formats:

  • A dictionary containing the keys "page" and "label", as well as optional "key" and "title" keywords.

    “page” should be the an absolute path to your page (e.g. “contents”, or “lib/mypage”). “label” is the text that will be displayed on the link, “title” is the tooltip set for the link, and “key” is the accesskey for selecting the link.

  • A 2-element tuple of (page, label)

  • A 4-element tuple of (page, title, key, label)

  • The predefined string "toc", which is replaced with a table of contents link to your master document.

relbar_links_after

When inserting the links, this extension will place them as far left as possible, so long as they are to the right of any links (whose labels) included in this list. Defaults to ["next", "previous"].

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 Cloud) to distinguish these special object-description-level sections from the document-level ones, the section elements are assigned two extra css classes: 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 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 the tilde prefix can be used (e.g. :raises ~myapp.MyException:), resulting in a proper crosslink, with only the final class name being displayed; much like 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
  • gc:project – link to Google Code 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.

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

Note

This feature has been submitted to the Sphinx issue tracker. If and when the patch is accepted (or an alternative is added to Sphinx), this extension will be deprecated and eventually 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 maps all defined references (made via :ref: or :doc:) to a (page, anchor, title) list.

This is useful e.g. 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

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.

: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_styling_embed_css

Controls whether or not the custom css file should be included. Set to True to enable, False to disable. By default (None), enabled for all Sphinx themes which aren’t part of this package.

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

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

Normal 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
Centered 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
Width x1 Width x2 Width x3
Header 1 Center 1 Right 1
Header 2 Center 2 Right 2
Header 3 Center 3 Right 3

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()

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

Nested Section

Parameters:arg – xxx
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.8.3 (2017-2-8)

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

1.8.2 (2017-1-30)

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

1.8.1 (2017-1-30)

  • 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)

  • Admonitions now support “without-title” class to hide title prefix (“Note”, “See also”, etc)
  • Added role_index extension
  • Added page_only extension
  • Fixed index_styling extension to be compatible with Sphinx 1.4
  • Sticky sidebar code now allows sidebar to be scrolled independantly of main document – just scroll mouse while overing over sidebar.
  • Sidebar can now be viewed from mobile mode; hidden state is stored independantly of large screen menu.
  • collapsablesidebar flag is now ignored, sidebar is always collapsable. flag will be removed in 1.9.
  • A large amount of the sidebar css & js was rewritten, many of the DOM classes have changed.
  • Now requires Sphinx >= 1.4.

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.