===============================================================
Notes On Sphinx Themes For RestructuredText Based Documentation
===============================================================

:Abstract:  Notes on Sphinx Themes and customization

:Author: Thava Alagu
:Date: 25 Jan 2013

.. contents::
        :depth: 2

.. _PyPI: http://pypi.python.org/pypi
.. |PyPI| replace:: Python Package Index
.. _Sphinx: http://sphinx-doc.org/
.. _Sphinx Theming: http://sphinx-doc.org/theming.html
.. _Python: http://www.python.org/
.. |RST| replace:: RestructuredText
.. _RST: http://docutils.sourceforge.net/rst.html


References
==========

- Sphinx_ Python Document Generator
- |PyPI|_
- `Sphinx Theming`_ 

Introduction
============

Sphinx_ document generation tool was originally created for Python_ 
documentation. However it has grown to be very powerful general purpose
documentation system based on |RST|_.

`Sphinx Theming`_ is highly customizable. This document describes
the resources and procedures about how to get and customize these themes.

I use this extensively to consolidate my own technical notes written
using |RST|. Sphinx generates a nice consolidated documentation to
view them. 

Sphinx Example Site Customization Tutorial
==========================================

You may want to look at `Sphinx example site customization Tutorial`__
first for an example. 

.. __: http://matplotlib.org/sampledoc/

Basically this involves following steps:

* Run *sphinx-quickstart* to generate a build template.
* Change index.rst file to include yourfile.rst
* Customize the following files::

    $ ls _static/ _templates/

    _static/:
    basic_screenshot.png        default.css             logo.png

    _templates/:
    layout.html

This gives some fundamental ideas about customization. 
All these above changes are applied on top of the basic built-in theme
that is in effect. You can change that theme too if you like. 

Built-in Themes
===============

To see the list of built-in themes available, look inside your Python installation::

  $ ls lib/python2.7/*-packages/sphinx/themes/

  agogo/    basic/      default/      epub/  haiku/  nature/  pyramid/  
  scrolls/  sphinxdoc/  traditional/

See `Sphinx Theming`_ to preview their look and feel.
Built-in themes come with certain amount of customization options.
You can specify following in your conf.py file as an example::

   html_theme = "default"
   html_theme_options = {
       "rightsidebar": "true",
       "stickysidebar": "true",
       "relbarbgcolor": "black"
   }

If this is more than what you need, you can stop here.
If you want further customization, read on.

Installing Additional Themes
============================

Go to |PyPI|_ and search for *Sphinx theme* or *Sphinx template*.
Here are some of the themes I chose to install from that list::

  $ themes="  sphinxjp.themes.basicstrap
              sphinxjp.themes.bizstyle
              sphinxjp.themes.dotted
              sphinxjp.themes.htmlslide
              sphinxjp.themes.impressjs
              sphinxjp.themes.s6
              sphinxjp.themes.trstyle
              "
  $ pip install $themes

To preview these themes, usually you just configure your conf.py, like below ::

  # basicstrap / bizstyle / dotted / htmlslide / impressjs / s6 / trstyle
  html_theme=basicstrap  
  html_theme_options = {}

  $ make html

Refer to the theme specific documentation from |PyPI|_ package page for
more information.

Generating Slides using RST
===========================

It is very handy to be able to generate presentation slides
by writing |RST|_ text. There are few such extensions
among the earlier mentioned sphinxjp.* themes:

* *impressjs*: For extreme visual effects like rotating and zooming.
* *htmlslide*
* *S6*

.. _impress : http://bartaz.github.com/impress.js
.. _impressjs : impress_

The impressjs_ support is very impressive.
You can look at the `impressjs sphinx extension demo`__ page. 
The source for the above demo is `here`__

.. __: http://packages.python.org/sphinxjp.themes.impressjs
.. __: http://packages.python.org/sphinxjp.themes.impressjs/_sources/index.txt

Conclusion
==========

After comparing many themes, I found the default theme is the best
after tweaking for my taste: I enabled the rightsidebar instead of left.
The next best built-in theme I liked is Pyramid with clean look. 
Next, among sphinxjp themes I liked bizstyle theme for general use. 
However, these are very subjective to one's tastes.

There are also numerous other Sphinx themes-- every major
project such as django provides it's own customized theme.
It is easy to get inspiration by looking at some of them
and just pick something you like as the base and customize it
further if needed.

Often, by tweaking some options (like just increasing the fontsize),
you can achieve dramatic improvements to suit your taste.

Source Document
============================================

This document has been written using |RST| and converted to HTML using rst2html__
command.

.. __: http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py

See the `document source text`__

.. __:  /notes/notes-sphinx-themes.txt

.. raw:: html

  <!-- AddThis Button BEGIN -->
  <div class="addthis_toolbox addthis_default_style ">
  <a class="addthis_button_facebook_like" fb:like:layout="button_count"></a>
  <a class="addthis_button_tweet"></a>
  <a class="addthis_button_pinterest_pinit"></a>
  <a class="addthis_counter addthis_pill_style"></a>
  </div>
  <script type="text/javascript"
  src="//s7.addthis.com/js/300/addthis_widget.js#pubid=ra-4f279ca549ba40bb"></script>
  <!-- AddThis Button END -->
  <hr/>
  <div class="footer"> <center> &copy; Thava Alagu  2013  </center> </div>