diff --git a/AUTHORS b/AUTHORS index 92deb7910..10120c7b4 100644 --- a/AUTHORS +++ b/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 diff --git a/CHANGES b/CHANGES index 506ef4b8c..a8a0bf7ba 100644 --- a/CHANGES +++ b/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`` diff --git a/doc/conf.py b/doc/conf.py index b268a13f0..e009fa1b4 100644 --- a/doc/conf.py +++ b/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' diff --git a/doc/theming.rst b/doc/theming.rst index ca6e8b2d6..fc8ef236d 100644 --- a/doc/theming.rst +++ b/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. diff --git a/sphinx/themes/default/layout.html b/sphinx/themes/default/layout.html new file mode 100644 index 000000000..43ee2cdf4 --- /dev/null +++ b/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 %} diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t index 8afa1a95f..f200a0fea 100644 --- a/sphinx/themes/default/static/default.css_t +++ b/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 }}; diff --git a/sphinx/themes/default/static/sidebar.js b/sphinx/themes/default/static/sidebar.js new file mode 100644 index 000000000..28eefc334 --- /dev/null +++ b/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( + '
«
' + ); + 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