cloud_sptheme-1.6/ 0000755 0001750 0001750 00000000000 12257647527 015362 5 ustar biscuit biscuit 0000000 0000000 cloud_sptheme-1.6/docs/ 0000755 0001750 0001750 00000000000 12257647527 016312 5 ustar biscuit biscuit 0000000 0000000 cloud_sptheme-1.6/docs/index.rst 0000644 0001750 0001750 00000004633 12257647306 020154 0 ustar biscuit biscuit 0000000 0000000 ===============================================
The Cloud Sphinx Theme
===============================================
This is release |release| of a small Python package named
:mod:`!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
========
Themes
------
:doc:`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:
:mod:`cloud_sptheme.ext.index_styling`
Adds additional css styling classes to the index page.
:mod:`cloud_sptheme.ext.relbar_toc`
Adds a TOC link to the top navigation controls.
Generic Extensions
------------------
This package also provides a few extra Sphinx extensions which may be useful
when documenting Python projects; and should be theme-agnostic:
:mod:`cloud_sptheme.ext.autodoc_sections`
Patches the :mod:`sphinx.ext.autodoc` to handle RST section headers
inside docstrings.
:mod:`cloud_sptheme.ext.issue_tracker`
Adds a special ``:issue:`` role for quickly linking to
your project's issue tracker.
:mod:`cloud_sptheme.ext.escaped_samp_literals`
Patches Sphinx to permit escaped ``{}`` characters within a ``:samp:`` role.
:mod:`cloud_sptheme.ext.table_styling`
Enhances ``.. table`` directive to support per-column
text alignment and other layout features.
Reference
---------
:doc:`install`
requirements and installations instructions
:doc:`history`
history of current and past releases
Online Resources
================
.. rst-class:: html-plain-table
====================== ===================================================
Homepage: ``_
Online Docs: ``_
Download & PyPI: ``_
====================== ===================================================
cloud_sptheme-1.6/docs/history.rst 0000644 0001750 0001750 00000000065 12214647252 020532 0 ustar biscuit biscuit 0000000 0000000 .. index:: cloud; changelog
.. include:: ../CHANGES
cloud_sptheme-1.6/docs/copyright.rst 0000644 0001750 0001750 00000000063 12214647252 021037 0 ustar biscuit biscuit 0000000 0000000 .. index:: cloud; license
.. include:: ../LICENSE
cloud_sptheme-1.6/docs/conf.py 0000644 0001750 0001750 00000021706 12257634334 017607 0 ustar biscuit biscuit 0000000 0000000 # -*- coding: utf-8 -*-
"""
Sphinx configuration file for the cloud_sptheme documentation.
This file is execfile()d with the current directory set to its containing dir.
Note that not all possible configuration values are present in this
autogenerated file. All configuration values have a default; values that are
commented out serve to show the default.
"""
#=============================================================================
# environment setup
#=============================================================================
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
##sys.path.insert(0, os.path.abspath('.'))
# make sure root of source dir in sys.path
sys.path.insert(0, os.path.abspath(os.pardir))
#=============================================================================
# imports
#=============================================================================
# import cloud_sptheme for themes, etc
import cloud_sptheme as csp
#=============================================================================
# General configuration
#=============================================================================
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.1'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
# standard sphinx extensions
'sphinx.ext.autodoc',
'sphinx.ext.todo',
# cloud's extensions
'cloud_sptheme.ext.autodoc_sections',
'cloud_sptheme.ext.index_styling',
'cloud_sptheme.ext.relbar_toc',
'cloud_sptheme.ext.escaped_samp_literals',
'cloud_sptheme.ext.issue_tracker',
'cloud_sptheme.ext.table_styling',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'contents'
# The frontpage document.
index_doc = 'index'
# General information about the project.
project = "Cloud Sphinx Theme"
author = "Assurance Technologies, LLC"
copyright = "2010-2012, " + author
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# release: The full version, including alpha/beta/rc tags.
# version: The short X.Y version.
from cloud_sptheme import __version__ as release
version = csp.get_version(release)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
##language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
##today = ''
# Else, today_fmt is used as the format for a strftime call.
##today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
# may revise/remove this
"lib/cloud_sptheme.make_helper.rst",
]
# The reST default role (used for this markup: `text`) to use for all documents.
##default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
##add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
##show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = [ "cloud_sptheme." ]
#=============================================================================
# Options for all output
#=============================================================================
todo_include_todos = True
keep_warnings = True
issue_tracker_url = "bb:ecollins/cloud_sptheme"
#=============================================================================
# Options for HTML output
#=============================================================================
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = os.environ.get("SPHINX_THEME") or 'cloud'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {}
if csp.is_cloud_theme(html_theme):
html_theme_options.update(
roottarget=index_doc,
)
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [csp.get_theme_dir()]
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
html_title = "%s v%s Documentation" % (project, release)
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "%s %s Documentation" % (project, version)
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = os.path.join("_static", "masthead.png")
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
##html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
##html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
##html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
##html_additional_pages = {}
# If false, no module index is generated.
##html_domain_indices = True
# If false, no index is generated.
##html_use_index = True
# If true, the index is split into individual pages for each letter.
##html_split_index = False
# If true, links to the reST sources are added to the pages.
##html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
##html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
##html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
##html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
##html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = project + 'Doc'
#=============================================================================
# Options for LaTeX output
#=============================================================================
# The paper size ('letter' or 'a4').
##latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
##latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
(index_doc, project + '.tex', project + ' Documentation',
author, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
##latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
##latex_use_parts = False
# If true, show page references after internal links.
##latex_show_pagerefs = False
# If true, show URL addresses after external links.
##latex_show_urls = False
# Additional stuff for the LaTeX preamble.
##latex_preamble = ''
# Documents to append as an appendix to all manuals.
##latex_appendices = []
# If false, no module index is generated.
##latex_domain_indices = True
#=============================================================================
# Options for manual page output
#=============================================================================
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(index_doc, project, project + ' Documentation',
[author], 1)
]
#=============================================================================
# EOF
#=============================================================================
cloud_sptheme-1.6/docs/lib/ 0000755 0001750 0001750 00000000000 12257647527 017060 5 ustar biscuit biscuit 0000000 0000000 cloud_sptheme-1.6/docs/lib/cloud_sptheme.ext.relbar_toc.rst 0000644 0001750 0001750 00000001272 12214647252 025345 0 ustar biscuit biscuit 0000000 0000000 =================================================================
:mod:`cloud_sptheme.ext.relbar_toc` - adds TOC entry to relbar
=================================================================
.. module:: cloud_sptheme.ext.relbar_toc
:synopsis: adds TOC entry to right side of relbar
Overview
========
This Sphinx extension automatically inserts a Table Of Contents
entry into the navigation bar (``relbar``) at the top and bottom of all pages;
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 :doc:`/cloud_theme`).
cloud_sptheme-1.6/docs/lib/cloud_sptheme.ext.index_styling.rst 0000644 0001750 0001750 00000002222 12214647252 026105 0 ustar biscuit biscuit 0000000 0000000 ==========================================================================
:mod:`cloud_sptheme.ext.index_styling` - improves css styling for genindex
==========================================================================
.. module:: cloud_sptheme.ext.index_styling
:synopsis: adds additional css styling to general index
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. :doc:`/cloud_theme`)
provide addtional 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
:samp:`...` tag.
- If the entry contains a location (e.g. ``myclass in module myapp``),
the ``myapp`` portion is wrapped in a ``...`` tag.
* Entries which don't fit into one of the above categories are not modified.
cloud_sptheme-1.6/docs/lib/cloud_sptheme.rst 0000644 0001750 0001750 00000000633 12214647252 022433 0 ustar biscuit biscuit 0000000 0000000 ===================================================================================
:mod:`cloud_sptheme` - helper functions
===================================================================================
.. module:: cloud_sptheme
:synopsis: helper functions
The main :mod:`!cloud_sptheme` module contains the following helper functions:
.. autofunction:: get_theme_dir
.. autofunction:: get_version
cloud_sptheme-1.6/docs/lib/cloud_sptheme.ext.escaped_samp_literals.rst 0000644 0001750 0001750 00000002323 12214647252 027552 0 ustar biscuit biscuit 0000000 0000000 ==================================================================================================
:mod:`cloud_sptheme.ext.escaped_samp_literals` - permits escaped bracket characters in *samp* role
==================================================================================================
.. module:: cloud_sptheme.ext.escaped_samp_literals
:synopsis: support 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:
:samp:`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-1.6/docs/lib/cloud_sptheme.ext.issue_tracker.rst 0000644 0001750 0001750 00000004067 12214647252 026101 0 ustar biscuit biscuit 0000000 0000000 ===================================================================================
:mod:`cloud_sptheme.ext.issue_tracker` - support for `issue` text role
===================================================================================
.. module:: cloud_sptheme.ext.issue_tracker
:synopsis: quickly create links to project's issue tracker with ``:issue:`` 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:
* :samp:`bb:{user}/{project}` -- link to BitBucket issue tracker for specified project
* :samp:`gh:{user}/{project}` -- link to GitHub issue tracker for specified project
* :samp:`gc:{project}` -- link to Google Code issue tracker for specified project
* string containng 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 ```` tag
will have an ``issue`` CSS class added to it.
cloud_sptheme-1.6/docs/lib/cloud_sptheme.ext.table_styling.rst 0000644 0001750 0001750 00000014435 12257631475 026105 0 ustar biscuit biscuit 0000000 0000000 ===========================================================================
:mod:`cloud_sptheme.ext.table_styling` - adds directives for styling tables
===========================================================================
.. module:: cloud_sptheme.ext.table_styling
:synopsis: 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:
.. table:: Optional Caption
:widths: 3 2 1
:column-alignment: left center right
:column-wrapping: yes yes no
: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.
=========== =========== ===========
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-seperated 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 relevent parts of the above directives.
While this extension is primarily tested with :mod:`!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-1.6/docs/lib/cloud_sptheme.make_helper.rst 0000644 0001750 0001750 00000004563 12214647252 024714 0 ustar biscuit biscuit 0000000 0000000 ====================================================================
:mod:`cloud_sptheme.make_helper` - sphinx-build Makefile replacement
====================================================================
.. module:: cloud_sptheme.make_helper
:synopsis: sphinx-build Makefile replacement
This module was written to solve one specific task:
to provide an alternative to the ``Makefile`` and ``make.bat`` scripts
found in many Sphinx projects. Most sphinx projects rely on the presence
of :command:`make`, do not frequently need documentation built on windows,
and don't find the need to update the makefile once set up. However,
for the small subset of projects this doesn't include, this class
provides an easy pure-python way to make a cross-platform build script.
Usage
=====
In order to use this script, go to your documentation's source directory,
and include the following fragment as the file ``make.py``::
"Makefile for Sphinx documentation, adapted to python"
import os
from cloud_sptheme.make_helper import SphinxMaker
if __name__ == "__main__":
SphinxMaker.execute(root_dir=os.path.join(__file__,os.pardir))
Once done, this script can be invoked via :samp:`python docs/make.py {options}`,
in the same manner as the Sphinx Makefile and make.bat script.
Any new features added to SphinxMaker via cloud_sptheme will automatically become
available to all packages using this stub.
Interface
=========
.. class:: SphinxMaker(root_dir=None)
:param root_dir:
absolute path pointing to documentation source directory.
The following are class attributes, but they may be
overridden via subclass, constructor, or environment variable
(in increasing order of precedence).
.. attribute:: BUILD
the build directory. this defaults to ``_build``,
.. attribute:: SPHINXBUILD
path to sphinx-build script, defaults to ``sphinx-build``.
.. attribute:: PAPER
paper size for latex, defaults to ``letter``.
.. attribute:: SERVEHTML_PORT
port for ``servehtml`` to launch a webserver on, defaults to 8000.
.. todo::
SphinxMaker does not currently include all the build targets that sphinx-quickstart's Makefile contains,
this should be fixed.
SphinxMaker may currently contain some assumptions which don't apply to some sphinx project layouts,
these should be identified and made configurable.
cloud_sptheme-1.6/docs/lib/cloud_sptheme.ext.autodoc_sections.rst 0000644 0001750 0001750 00000003334 12214647252 026577 0 ustar biscuit biscuit 0000000 0000000 ===================================================================================
:mod:`cloud_sptheme.ext.autodoc_sections` - support for ReST sections in docstrings
===================================================================================
.. module:: cloud_sptheme.ext.autodoc_sections
:synopsis: support for ReST sections in docstrings
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).
This extension detects all single-line (but not double-line) headers,
and turns them into a series of definition lists (````), with the header
name as the term (``- ``), and the section's content as the definition (``
- ``).
Internals
=========
In order for Sphinx themes (like Cloud)
to distinguish these from regular definition lists,
the ``
`` elements generated by this extension are assigned
two css classes: ``nested-section`` and :samp:`nested-section-{level}`.
Depending on the theme, these may require additional styling rules.
.. warning::
This extension is currently somewhat fragile:
it works reliably for the common cases,
but may not behave properly given unexpected input.
.. todo::
This extension has a number of things which could be improved:
* Handle double-lined headers as well as single-lined ones
* Use Sphinx's ReST parser, instead of the custom hack currently in place
* Instead of outputing definition lists; it should output proper paragraph markup,
with ```` headings.
* Subsections should be included in Sphinx's indexing.
cloud_sptheme-1.6/docs/cloud_theme.rst 0000644 0001750 0001750 00000017020 12223360436 021314 0 ustar biscuit biscuit 0000000 0000000 .. index:: cloud; sphinx theme, sphinx theme; cloud
====================
"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 ```` 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 ``""``, which uses the table of contents).
``logotarget``
Sets the page which the sidebar logo (if any) should point to
(defaults to the special value ````, 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``).
``compact_width``
Sets the maximum width where the "compact" layout will be used.
This layout omits some of the padding and styling,
and is more suitable for smaller screens (defaults to ``960px``).
``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``).
Sidebar Layout & Styling
------------------------
``rightsidebar``
whether the sidebar is on the right side instead of the left
(defaults to ``false``).
``collapsiblesidebar``
whether the sidebar can be hidden or not (defaults to ``true``).
``defaultcollapsed``
whether the sidebar should start collapsed (defaults to ``false``).
``stickysidebar``
whether the sidebar should "stick" in the current window
(defaults to ``true``), otherwise it will scroll along with the page.
``highlighttoc``
whether sidebar should highlight the sections which are currently
being viewed (defaults to ``true``).
``popuptoc``
by default, TOC entries which overflow the sidebar will be cut off
until the cursor hovers over the sidebar, at which point they will
expand across the document. to disable this feature (and make them
wrap within the sidebar), set ``popuptoc=false``.
Sidebar Labels
--------------
``sidebar_localtoc_title``
Override title of per-page table of contents (in ``localtoc.html`` sidebar).
defaults to ``Page content``.
``sidebar_prev_title``
Override title of link to previous page (in ``relations.html`` sidebar).
defaults to ``Previous page``.
``sidebar_next_title``
Override title of link to next page (in ``relations.html`` sidebar).
defaults to ``Next page``.
``sidebar_master_title``
Override title of the front-page document link (in ``quicklinks.html`` sidebar).
``sidebar_root_title``
Override title of the root document link (in ``quicklinks.html`` sidebar).
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 :mod:`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).
.. _cloud-theme-usage:
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" }
.. rst-class:: floater
.. seealso::
See the next page (:doc:`cloud_theme_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.
.. seealso::
The :mod:`~cloud_sptheme.ext.table_styling` extension
for additional table styling abilities, e.g. per-column text alignment.
cloud_sptheme-1.6/docs/install.rst 0000644 0001750 0001750 00000003253 12214647252 020501 0 ustar biscuit biscuit 0000000 0000000 .. index:: cloud; installation
=========================
Installation Instructions
=========================
Requirements
============
* Python >= 2.5 or Python 3
* `Sphinx `_ 1.1 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
.. index:: readthedocs.org; installation on
ReadTheDocs
===========
To use this theme on ``_:
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 :mod:`!cloud_sptheme`
when building your documentation.
Documentation
=============
The latest copy of this documentation should always be available at:
``_
If you wish to generate your own copy of the documentation,
you will need to:
1. Install `Sphinx `_ (1.1 or better)
2. Download the :mod:`!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 :samp:`{SOURCE}/build/sphinx/html/index.html`.
cloud_sptheme-1.6/docs/_static/ 0000755 0001750 0001750 00000000000 12257647527 017740 5 ustar biscuit biscuit 0000000 0000000 cloud_sptheme-1.6/docs/_static/masthead.svg 0000644 0001750 0001750 00000037457 12214647252 022253 0 ustar biscuit biscuit 0000000 0000000
cloud_sptheme-1.6/docs/_static/logo.svg 0000644 0001750 0001750 00000026330 12214647252 021411 0 ustar biscuit biscuit 0000000 0000000
cloud_sptheme-1.6/docs/_static/masthead.png 0000644 0001750 0001750 00000033203 12214647252 022221 0 ustar biscuit biscuit 0000000 0000000 PNG
IHDR ` U sBIT|d pHYs
B(x tEXtSoftware www.inkscape.org< IDATxyy;a_8")ʒ82ue'I//Ky>~"ϳrD,EGrdkX6K\$( D $b,e{t}u{ Hs}~}
"5&/W\5yY}pB,]+5YCI 8t2yyy177'=kooǏSGG
p
lY⡇wpk5=P.U jBʶR5&۫Ց#GTWW7416Fqs߱! !p";dϧw(RPh۴uۦm۷tGha^kzx\eq''OTu|ga!,jjl_F_3XqÅɔOr]vǷxcEto]C MBO܉OO3/D<ҒEQxhn-ӎVNco4N\ 3 o-$i~qFgy籃yJApJV ,@Bxz'T'~19G(*7K
)îrY:tH)!{َOϾ[5k`bJ > ;yw~;anwO<B _К!HCiPA-@ᑇ\8zo9gz}!AX6V=xu`*BlqO:U/P
o/:@%= OK"62cЀ B+To>A