1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
.. 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 ``<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``).
``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 <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" }
.. 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.
|
