.. _hieroglyph-themes:

================
 Styling Slides
================

Styling
-------

- Slides are contained in ``<article>`` elements
- Each slide has an HTML ``id`` that corresponds to the permalink ID
  generated by Sphinx (for example, you're currentling reading
  ``styling``).
- The heading level is added as a class; ie, ``level-2``
- Slides may be styled using a theme, or custom CSS.

Included Themes
---------------

Hieroglyph includes two :ref:`themes <custom-themes>`.

``slides``

  Two slides levels: the first level of headers become "section"
  headers, and the second become the real content.

``single-level``

  Only one style of slide, every slide has a title at the top.


Setting the Theme
-----------------

You can set your theme using the ``slide_theme`` configuration
setting.

::

  slide_theme = 'single-level'

If you're using a custom theme, you can also set the directory to look
in for themes::

  slide_theme_path = '...'


Incremental slides
------------------

.. slide:: Incremental Slides
   :level: 2

   .. rst-class:: build

   - Adding the ``build`` class to a container
   - To incrementally show its contents
   - Remember that *Sphinx* maps the basic ``class`` directive to
     ``rst-class``. For example::

       .. rst-class:: build

       - Bullet 1
       - Bullet 2


It's common to have a slide with a list of items that are shown one at
a time. Hieroglpyh supports this through the use of the ``build``
class. Let's add a third slide to ``index.rst`` that incrementally
displays a bulleted list.

::

  Show Bullets Incrementally
  ==========================

  .. rst-class:: build

  - Adding the ``build`` class to a container
  - To incrementally show its contents
  - Remember that *Sphinx* maps the basic ``class`` directive to
    ``rst-class``

Here the :rst:dir:`rst-class` directive causes the next element
to be built incrementally.

Displaying Images
-----------------

.. slide:: Displaying Images
   :level: 2

   * Images and static assets should go in the ``_static`` directory in
     your project
   * The :rst:dir:`image` directive lets you display an image
   * Hieroglyph includes support for showing an image full size in a
     slide (like the title slide in this deck).

   ::

     .. figure:: /_static/hieroglyphs.jpg
        :class: fill

        CC BY-SA http://www.flickr.com/photos/tamburix/2900909093/

You can include any image in a slide using the :rst:dir:`image`
directive. Just drop them in the ``_static`` directory in your
project.

Hieroglyph also includes some support for showing an image as the full
slide using the :rst:dir:`figure` directive. For example, the
Hieroglyph introductory slide deck uses the following markup::

  .. figure:: /_static/hieroglyphs.jpg
     :class: fill

     CC BY-SA http://www.flickr.com/photos/tamburix/2900909093/

The caption (license information above) is styled as an overlay on the
image.


Setting a Class on Slides
-------------------------

You can set the CSS class on a slide using the normal
:rst:dir:`rst-class` directive. (Sphinx remaps ``class`` to
:rst:dir:`rst-class` to avoid conflicts.) For example::

   .. rst-class:: myclass

   Slide Heading
   -------------

The :rst:dir:`rst-class` directive applies to the *next* following
element (the heading ``Slide Heading`` in this example).

You can also set a default class on slides using the
``slide_classes`` option of the :rst:dir:`slideconf` directive. Note
that specifying an explicit class will override the ``slide_classes``.

Included Styles
---------------

Hieroglyph includes some classes that for styling slides:

* ``appear``

   Case the slide to just appear, replacing the previous slide,
   instead of sliding from the right to left.

* ``fade-in``

   Causes the slide to quickly fade in and out, instead of sliding
   from the right to left.

.. _custom-css:

Custom CSS
----------

The standard Hieroglyph themes support adding a custom stylesheet with
the ``slide_theme_options`` dict in ``conf.py``::

  slide_theme_options = {'custom_css': 'custom.css'}

The custom CSS file should be located in the ``html_static_path``
(``_static`` by default).


.. _custom-js:

Adding Javascript
-----------------

In addition to a custom CSS file, it is sometimes useful to include
some custom Javascript for your slides. You can put this in your
static directory (``_static`` by default), and then reference it in
the ``slide_theme_options`` dict in ``conf.py``::

  slide_theme_options = {'custom_js': 'myslides.js'}


.. _custom-themes:

Creating  Themes
----------------

Hieroglyph themes are based on Sphinx's HTML `themes`_. Themes are
either a directory or zipfile, which contains a ``theme.conf`` file,
templates you wish to override, and a ``static/`` directory which
contains images, CSS, etc.

When defining a slide theme, inherit from the ``slides`` theme for
basic support. For example, the ``single-level`` them has the
following ``theme.conf``::

  [theme]
  inherit = slides
  stylesheet = single.css

  [options]
  custom_css =

In order to include the base slide styling, your theme's stylesheet
should begin with::

  @import url(slides.css);

``slides.css`` will be supplied by the base theme (``slides``).

See the Sphinx documentation for `themes`_ for more information.

.. _`themes`: http://sphinx.pocoo.org/theming.html