1.. highlight:: python 2 3.. _html-themes: 4 5HTML Theming 6============ 7 8Sphinx provides a number of builders for HTML and HTML-based formats. 9 10Builders 11-------- 12 13.. todo:: Populate when the 'builders' document is split up. 14 15 16Themes 17------ 18 19.. versionadded:: 0.6 20 21.. note:: 22 23 This section provides information about using pre-existing HTML themes. If 24 you wish to create your own theme, refer to 25 :doc:`/development/theming`. 26 27Sphinx supports changing the appearance of its HTML output via *themes*. A 28theme is a collection of HTML templates, stylesheet(s) and other static files. 29Additionally, it has a configuration file which specifies from which theme to 30inherit, which highlighting style to use, and what options exist for customizing 31the theme's look and feel. 32 33Themes are meant to be project-unaware, so they can be used for different 34projects without change. 35 36Using a theme 37~~~~~~~~~~~~~ 38 39Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these 40do not need to be installed, you only need to set the :confval:`html_theme` 41config value. For example, to enable the ``classic`` theme, add the following 42to :file:`conf.py`:: 43 44 html_theme = "classic" 45 46You can also set theme-specific options using the :confval:`html_theme_options` 47config value. These options are generally used to change the look and feel of 48the theme. For example, to place the sidebar on the right side and a black 49background for the relation bar (the bar with the navigation links at the 50page's top and bottom), add the following :file:`conf.py`:: 51 52 html_theme_options = { 53 "rightsidebar": "true", 54 "relbarbgcolor": "black" 55 } 56 57If the theme does not come with Sphinx, it can be in two static forms or as a 58Python package. For the static forms, either a directory (containing 59:file:`theme.conf` and other needed files), or a zip file with the same 60contents is supported. The directory or zipfile must be put where Sphinx can 61find it; for this there is the config value :confval:`html_theme_path`. This 62can be a list of directories, relative to the directory containing 63:file:`conf.py`, that can contain theme directories or zip files. For example, 64if you have a theme in the file :file:`blue.zip`, you can put it right in the 65directory containing :file:`conf.py` and use this configuration:: 66 67 html_theme = "blue" 68 html_theme_path = ["."] 69 70The third form is a Python package. If a theme you want to use is distributed 71as a Python package, you can use it after installing 72 73.. code-block:: bash 74 75 # installing theme package 76 $ pip install sphinxjp.themes.dotted 77 78Once installed, this can be used in the same manner as a directory or 79zipfile-based theme:: 80 81 html_theme = "dotted" 82 83For more information on the design of themes, including information about 84writing your own themes, refer to :doc:`/development/theming`. 85 86.. _builtin-themes: 87 88Builtin themes 89~~~~~~~~~~~~~~ 90 91.. cssclass:: longtable 92 93+--------------------+--------------------+ 94| **Theme overview** | | 95+--------------------+--------------------+ 96| |alabaster| | |classic| | 97| | | 98| *alabaster* | *classic* | 99+--------------------+--------------------+ 100| |sphinxdoc| | |scrolls| | 101| | | 102| *sphinxdoc* | *scrolls* | 103+--------------------+--------------------+ 104| |agogo| | |traditional| | 105| | | 106| *agogo* | *traditional* | 107+--------------------+--------------------+ 108| |nature| | |haiku| | 109| | | 110| *nature* | *haiku* | 111+--------------------+--------------------+ 112| |pyramid| | |bizstyle| | 113| | | 114| *pyramid* | *bizstyle* | 115+--------------------+--------------------+ 116 117.. |alabaster| image:: /_static/themes/alabaster.png 118.. |classic| image:: /_static/themes/classic.png 119.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png 120.. |scrolls| image:: /_static/themes/scrolls.png 121.. |agogo| image:: /_static/themes/agogo.png 122.. |traditional| image:: /_static/themes/traditional.png 123.. |nature| image:: /_static/themes/nature.png 124.. |haiku| image:: /_static/themes/haiku.png 125.. |pyramid| image:: /_static/themes/pyramid.png 126.. |bizstyle| image:: /_static/themes/bizstyle.png 127 128Sphinx comes with a selection of themes to choose from. 129 130.. cssclass:: clear 131 132These themes are: 133 134**basic** 135 This is a basically unstyled layout used as the base for the 136 other themes, and usable as the base for custom themes as well. The HTML 137 contains all important elements like sidebar and relation bar. There are 138 these options (which are inherited by the other themes): 139 140 - **nosidebar** (true or false): Don't include the sidebar. Defaults to 141 ``False``. 142 143 - **sidebarwidth** (int or str): Width of the sidebar in pixels. 144 This can be an int, which is interpreted as pixels or a valid CSS 145 dimension string such as '70em' or '50%'. Defaults to 230 pixels. 146 147 - **body_min_width** (int or str): Minimal width of the document body. 148 This can be an int, which is interpreted as pixels or a valid CSS 149 dimension string such as '70em' or '50%'. Use 0 if you don't want 150 a width limit. Defaults may depend on the theme (often 450px). 151 152 - **body_max_width** (int or str): Maximal width of the document body. 153 This can be an int, which is interpreted as pixels or a valid CSS 154 dimension string such as '70em' or '50%'. Use 'none' if you don't 155 want a width limit. Defaults may depend on the theme (often 800px). 156 157 - **navigation_with_keys** (true or false): Allow navigating to the 158 previous/next page using the keyboard's left and right arrows. Defaults to 159 ``False``. 160 161 - **globaltoc_collapse** (true or false): Only expand subsections 162 of the current document in ``globaltoc.html`` 163 (see :confval:`html_sidebars`). 164 Defaults to ``True``. 165 166 .. versionadded:: 3.1 167 168 - **globaltoc_includehidden** (true or false): Show even those 169 subsections in ``globaltoc.html`` (see :confval:`html_sidebars`) 170 which have been included with the ``:hidden:`` flag of the 171 :rst:dir:`toctree` directive. 172 Defaults to ``False``. 173 174 .. versionadded:: 3.1 175 176 - **globaltoc_maxdepth** (int): The maximum depth of the toctree in 177 ``globaltoc.html`` (see :confval:`html_sidebars`). Set it to -1 to allow 178 unlimited depth. Defaults to the max depth selected in the toctree directive. 179 180 .. versionadded:: 3.2 181 182**alabaster** 183 `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz 184 (especially as used in his Requests project), which was itself originally 185 based on @mitsuhiko's theme used for Flask & related projects. Refer to its 186 `installation page`_ for information on how to configure 187 :confval:`html_sidebars` for its use. 188 189 .. _Alabaster theme: https://pypi.org/project/alabaster/ 190 .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html 191 192**classic** 193 This is the classic theme, which looks like `the Python 2 194 documentation <https://docs.python.org/2/>`_. It can be customized via 195 these options: 196 197 - **rightsidebar** (true or false): Put the sidebar on the right side. 198 Defaults to ``False``. 199 200 - **stickysidebar** (true or false): Make the sidebar "fixed" so that it 201 doesn't scroll out of view for long body content. This may not work well 202 with all browsers. Defaults to ``False``. 203 204 - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript 205 snippet that makes the sidebar collapsible via a button on its side. 206 Defaults to ``False``. 207 208 - **externalrefs** (true or false): Display external links differently from 209 internal links. Defaults to ``False``. 210 211 There are also various color and font options that can change the color scheme 212 without having to write a custom stylesheet: 213 214 - **footerbgcolor** (CSS color): Background color for the footer line. 215 - **footertextcolor** (CSS color): Text color for the footer line. 216 - **sidebarbgcolor** (CSS color): Background color for the sidebar. 217 - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse 218 button (used when *collapsiblesidebar* is ``True``). 219 - **sidebartextcolor** (CSS color): Text color for the sidebar. 220 - **sidebarlinkcolor** (CSS color): Link color for the sidebar. 221 - **relbarbgcolor** (CSS color): Background color for the relation bar. 222 - **relbartextcolor** (CSS color): Text color for the relation bar. 223 - **relbarlinkcolor** (CSS color): Link color for the relation bar. 224 - **bgcolor** (CSS color): Body background color. 225 - **textcolor** (CSS color): Body text color. 226 - **linkcolor** (CSS color): Body link color. 227 - **visitedlinkcolor** (CSS color): Body color for visited links. 228 - **headbgcolor** (CSS color): Background color for headings. 229 - **headtextcolor** (CSS color): Text color for headings. 230 - **headlinkcolor** (CSS color): Link color for headings. 231 - **codebgcolor** (CSS color): Background color for code blocks. 232 - **codetextcolor** (CSS color): Default text color for code blocks, if not 233 set differently by the highlighting style. 234 235 - **bodyfont** (CSS font-family): Font for normal text. 236 - **headfont** (CSS font-family): Font for headings. 237 238**sphinxdoc** 239 The theme originally used by this documentation. It features 240 a sidebar on the right side. There are currently no options beyond 241 *nosidebar* and *sidebarwidth*. 242 243 .. note:: 244 245 The Sphinx documentation now uses 246 `an adjusted version of the sphinxdoc theme 247 <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_. 248 249**scrolls** 250 A more lightweight theme, based on `the Jinja documentation 251 <http://jinja.pocoo.org/>`_. The following color options are available: 252 253 - **headerbordercolor** 254 - **subheadlinecolor** 255 - **linkcolor** 256 - **visitedlinkcolor** 257 - **admonitioncolor** 258 259**agogo** 260 A theme created by Andi Albrecht. The following options are supported: 261 262 - **bodyfont** (CSS font family): Font for normal text. 263 - **headerfont** (CSS font family): Font for headings. 264 - **pagewidth** (CSS length): Width of the page content, default 70em. 265 - **documentwidth** (CSS length): Width of the document (without sidebar), 266 default 50em. 267 - **sidebarwidth** (CSS length): Width of the sidebar, default 20em. 268 - **rightsidebar** (true or false): Put the sidebar on the right side. 269 Defaults to ``True``. 270 - **bgcolor** (CSS color): Background color. 271 - **headerbg** (CSS value for "background"): background for the header area, 272 default a grayish gradient. 273 - **footerbg** (CSS value for "background"): background for the footer area, 274 default a light gray gradient. 275 - **linkcolor** (CSS color): Body link color. 276 - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2> 277 headings. 278 - **headerlinkcolor** (CSS color): Color for the backreference link in 279 headings. 280 - **textalign** (CSS *text-align* value): Text alignment for the body, default 281 is ``justify``. 282 283**nature** 284 A greenish theme. There are currently no options beyond 285 *nosidebar* and *sidebarwidth*. 286 287**pyramid** 288 A theme from the Pyramid web framework project, designed by Blaise Laflamme. 289 There are currently no options beyond *nosidebar* and *sidebarwidth*. 290 291**haiku** 292 A theme without sidebar inspired by the `Haiku OS user guide 293 <https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following 294 options are supported: 295 296 - **full_logo** (true or false, default ``False``): If this is true, the 297 header will only show the :confval:`html_logo`. Use this for large logos. 298 If this is false, the logo (if present) will be shown floating right, and 299 the documentation title will be put in the header. 300 301 - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**, 302 **hoverlinkcolor** (CSS colors): Colors for various body elements. 303 304**traditional** 305 A theme resembling the old Python documentation. There are 306 currently no options beyond *nosidebar* and *sidebarwidth*. 307 308**epub** 309 A theme for the epub builder. This theme tries to save visual 310 space which is a sparse resource on ebook readers. The following options 311 are supported: 312 313 - **relbar1** (true or false, default ``True``): If this is true, the 314 `relbar1` block is inserted in the epub output, otherwise it is omitted. 315 316 - **footer** (true or false, default ``True``): If this is true, the 317 `footer` block is inserted in the epub output, otherwise it is omitted. 318 319**bizstyle** 320 A simple bluish theme. The following options are supported 321 beyond *nosidebar* and *sidebarwidth*: 322 323 - **rightsidebar** (true or false): Put the sidebar on the right side. 324 Defaults to ``False``. 325 326.. versionadded:: 1.3 327 'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme. 328 329.. versionchanged:: 1.3 330 The 'default' theme has been renamed to 'classic'. 'default' is still 331 available, however it will emit a notice that it is an alias for the new 332 'alabaster' theme. 333 334Third Party Themes 335~~~~~~~~~~~~~~~~~~ 336 337.. cssclass:: longtable 338 339+--------------------+--------------------+ 340| **Theme overview** | | 341+--------------------+--------------------+ 342| |sphinx_rtd_theme| | | 343| | | 344| *sphinx_rtd_theme* | | 345+--------------------+--------------------+ 346 347.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png 348 349There are many third-party themes available. Some of these are general use, 350while others are specific to an individual project. A section of third-party 351themes is listed below. Many more can be found on PyPI__, GitHub__, GitLab__ and 352sphinx-themes.org__. 353 354.. cssclass:: clear 355 356**sphinx_rtd_theme** 357 `Read the Docs Sphinx Theme`_. 358 This is a mobile-friendly sphinx theme that was made for readthedocs.org. 359 View a working demo over on readthedocs.org. You can get install and options 360 information at `Read the Docs Sphinx Theme`_ page. 361 362 .. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/ 363 364 .. versionchanged:: 1.4 365 **sphinx_rtd_theme** has become optional. 366 367 368.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme 369.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type= 370.. __: https://gitlab.com/explore?name=sphinx+theme 371.. __: https://sphinx-themes.org/ 372
