In the default theme, the sidebar can experimentally now be made collapsible using the new `collapsiblesidebar` theme option.

AUTHORS

@@ -19,6 +19,7 @@ Other contributors, listed alphabetically, are:
 * Martin Mahner -- nature theme
 * Will Maier -- directory HTML builder
 * Roland Meister -- epub builder
+* Ezio Melotti -- collapsible sidebar JavaScript
 * Daniel Neuhäuser -- JavaScript domain
 * Christopher Perkins -- autosummary integration
 * Benjamin Peterson -- unittests

CHANGES

@@ -87,6 +87,10 @@ Features added
     ``domain`` and ``domain-rolename``.
   - References now get the class ``internal`` if they are internal to
     the whole project, as opposed to internal to the current page.
+  - External references can be styled differently with the new
+    ``externalrefs`` theme option for the default theme.
+  - In the default theme, the sidebar can experimentally now be made
+    collapsible using the new ``collapsiblesidebar`` theme option.
   - #129: Toctrees are now wrapped in a ``div`` tag with class
     ``toctree-wrapper`` in HTML output.
   - The ``toctree()`` callable in templates now has a ``maxdepth``

doc/conf.py

@@ -18,7 +18,8 @@ version = sphinx.__released__
 release = version
 show_authors = True
 
-html_theme = 'sphinxdoc'
+html_theme = 'default'
+html_theme_options = {'collapsiblesidebar': True, 'stickysidebar': False}
 modindex_common_prefix = ['sphinx.']
 html_static_path = ['_static']
 html_index = 'index.html'

doc/theming.rst

@@ -105,6 +105,11 @@ These themes are:
     doesn't scroll out of view for long body content.  This may not work well
     with all browsers.  Defaults to false.
 
+  - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
+    snippet that makes the sidebar collapsible via a button on its side.
+    *Doesn't work together with "rightsidebar" or "stickysidebar".* Defaults to
+    false.
+
   - **externalrefs** (true or false): Display external links differently from
     internal links.  Defaults to false.
 

sphinx/themes/default/layout.html

@@ -0,0 +1,14 @@
+{#
+    default/layout.html
+    ~~~~~~~~~~~~~~~~~~~
+
+    Sphinx layout template for the default theme.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% extends "basic/layout.html" %}
+
+{% if theme_collapsiblesidebar|tobool %}
+{% set script_files = script_files + ['_static/sidebar.js'] %}
+{% endif %}

sphinx/themes/default/static/default.css_t

@@ -164,7 +164,7 @@ a:hover {
     text-decoration: underline;
 }
 
-{% if theme_externalrefs %}
+{% if theme_externalrefs|tobool %}
 a.external {
    text-decoration: none;
    border-bottom: 1px dashed {{ theme_linkcolor }};

sphinx/themes/default/static/sidebar.js

@@ -0,0 +1,147 @@
+/*
+ * sidebar.js
+ * ~~~~~~~~~~
+ *
+ * This script makes the Sphinx sidebar collapsible.
+ *
+ * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
+ * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
+ * used to collapse and expand the sidebar.
+ *
+ * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
+ * and the width of the sidebar and the margin-left of the document
+ * are decreased. When the sidebar is expanded the opposite happens.
+ * This script saves a per-browser/per-session cookie used to
+ * remember the position of the sidebar among the pages.
+ * Once the browser is closed the cookie is deleted and the position
+ * reset to the default (expanded).
+ *
+ * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+$(function() {
+  // global elements used by the functions.
+  // the 'sidebarbutton' element is defined as global after its
+  // creation, in the add_sidebar_button function
+  var bodywrapper = $('.bodywrapper');
+  var sidebar = $('.sphinxsidebar');
+  var sidebarwrapper = $('.sphinxsidebarwrapper');
+
+  // original margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar expanded
+  var bw_margin_expanded = bodywrapper.css('margin-left');
+  var ssb_width_expanded = sidebar.width();
+
+  // margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar collapsed
+  var bw_margin_collapsed = '.8em';
+  var ssb_width_collapsed = '.8em';
+
+  // colors used by the current theme
+  var dark_color = $('.related').css('background-color');
+  var light_color = $('.document').css('background-color');
+
+  function sidebar_is_collapsed() {
+    return sidebarwrapper.is(':not(:visible)');
+  }
+
+  function toggle_sidebar() {
+    if (sidebar_is_collapsed())
+      expand_sidebar();
+    else
+      collapse_sidebar();
+  }
+
+  function collapse_sidebar() {
+    sidebarwrapper.hide();
+    sidebar.css('width', ssb_width_collapsed);
+    bodywrapper.css('margin-left', bw_margin_collapsed);
+    sidebarbutton.css({
+        'margin-left': '0',
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('»');
+    sidebarbutton.attr('title', 'Expand sidebar');
+    document.cookie = 'sidebar=collapsed';
+  }
+
+  function expand_sidebar() {
+    bodywrapper.css('margin-left', bw_margin_expanded);
+    sidebar.css('width', ssb_width_expanded);
+    sidebarwrapper.show();
+    sidebarbutton.css({
+        'margin-left': ssb_width_expanded-12,
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('«');
+    sidebarbutton.attr('title', 'Collapse sidebar');
+    document.cookie = 'sidebar=expanded';
+  }
+
+  function add_sidebar_button() {
+    sidebarwrapper.css({
+        'float': 'left',
+        'margin-right': '0',
+        'width': ssb_width_expanded - 28
+    });
+    // create the button
+    sidebar.append(
+        '<div id="sidebarbutton"><span>&laquo;</span></div>'
+    );
+    var sidebarbutton = $('#sidebarbutton');
+    // find the height of the viewport to center the '<<' in the page
+    var viewport_height;
+    if (window.innerHeight)
+ 	  viewport_height = window.innerHeight;
+    else
+	  viewport_height = $(window).height();
+    sidebarbutton.find('span').css({
+        'display': 'block',
+        'margin-top': (viewport_height - sidebar.position().top - 20) / 2
+    });
+
+    sidebarbutton.click(toggle_sidebar);
+    sidebarbutton.attr('title', 'Collapse sidebar');
+    sidebarbutton.css({
+        'color': '#FFFFFF',
+        'border-left': '1px solid ' + dark_color,
+        'font-size': '1.2em',
+        'cursor': 'pointer',
+        'height': bodywrapper.height(),
+        'padding-top': '1px',
+        'margin-left': ssb_width_expanded - 12
+    });
+
+    sidebarbutton.hover(
+      function () {
+          $(this).css('background-color', dark_color);
+      },
+      function () {
+          $(this).css('background-color', light_color);
+      }
+    );
+  }
+
+  function set_position_from_cookie() {
+    if (!document.cookie)
+      return;
+    var items = document.cookie.split(';');
+    for(var k=0; k<items.length; k++) {
+      var key_val = items[k].split('=');
+      var key = key_val[0];
+      if (key == 'sidebar') {
+        var value = key_val[1];
+        if ((value == 'collapsed') && (!sidebar_is_collapsed()))
+          collapse_sidebar();
+        else if ((value == 'expanded') && (sidebar_is_collapsed()))
+          expand_sidebar();
+      }
+    }
+  }
+
+  add_sidebar_button();
+  var sidebarbutton = $('#sidebarbutton');
+  set_position_from_cookie();
+});

sphinx/themes/default/theme.conf

@@ -6,7 +6,7 @@ pygments_style = sphinx
 [options]
 rightsidebar = false
 stickysidebar = false
-
+collapsiblesidebar = false
 externalrefs = false
 
 footerbgcolor    = #11303d