.. 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 ``<h3>`` sections with ``.. rst-class:: emphasized``
      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``).

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``).

``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``).

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 <http://www.google.com/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" }

Toggleable Sections
-------------------
By adding ``.. rst-class:: html-toggle`` before a ReST section,
it can be made toggleable::

    .. rst-class:: html-toggle

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

    This section is collapsed by default.

Toggleable sections start out collapsed by default.
You can use ``.. rst-class:: html-toggle expanded`` to override this.

.. seealso:: the `Feature Test`_ for an example of a toggleable section.

Other Styling Helpers
---------------------
* Adding ``.. rst-class:: emphasized`` can be used to give a solid background
  to 3rd level sections, which are normally rendered w/ out a background
  under this theme.

* Adding ``.. rst-class:: html-plain-table`` can be used to remove
  the alternate row shading and other styling from a RST table.

Feature Test
============

Inline Styles
-------------
External link prefixed with an arrow: `<http://www.google.com>`_.

Issue link prefixed with a star: :issue:`2718`.

.. rst-class:: html-toggle emphasized

.. _toggle-test-link:

Toggleable Section
------------------
This section is collapsed by default.
But if a visitor follows a link to this section or something within it
(such as :ref:`this <toggle-test-link>`), it will automatically be expanded.

Admonition Styles
-----------------
.. note::
    This is a note.

.. warning::

    This is warning.

.. seealso::

    This is a "see also" message.

.. todo::

    This is a todo message.

.. deprecated:: XXX This is a deprecation warning.
