#4246: Limit width of text body for all themes

Author: timhoffm

AUTHORS

@@ -34,6 +34,7 @@ Other contributors, listed alphabetically, are:
 * Horst Gutmann -- internationalization support
 * Martin Hans -- autodoc improvements
 * Doug Hellmann -- graphviz improvements
+* Tim Hoffmann -- theme improvements
 * Timotheus Kampik - JS theme & search enhancements
 * Dave Kuhlman -- original LaTeX writer
 * Blaise Laflamme -- pyramid theme

CHANGES

@@ -13,6 +13,8 @@ Incompatible changes
 * #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
 * #4226: apidoc: Generate new style makefile (make-mode)
 * #4274: sphinx-build returns 2 as an exit code on argument error
+* #4246: Limit width of text body for all themes. Conifigurable via theme
+  options ``body_min_width`` and ``body_max_width``.
 
 Deprecated
 ----------

doc/theming.rst

@@ -114,8 +114,19 @@ These themes are:
   - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
     ``False``.
 
-  - **sidebarwidth** (an integer): Width of the sidebar in pixels.  (Do not
-    include ``px`` in the value.)  Defaults to 230 pixels.
+  - **sidebarwidth** (int or str): Width of the sidebar in pixels.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'.  Defaults to 230 pixels.
+
+  - **body_min_width** (int or str): Minimal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 0 if you don't want
+    a width limit. Defaults may depend on the theme (often 450px).
+
+  - **body_max_width** (int or str): Maximal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 'none' if you don't
+    want a width limit. Defaults may depend on the theme (often 800px).
 
 * **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally based on

sphinx/jinja2glue.py

@@ -45,6 +45,25 @@ def _toint(val):
         return 0
 
 
+def _todim(val):
+    # type (int or unicode) -> unicode
+    """
+    Make val a css dimension. In particular the following transformations
+    are performed:
+
+    - None -> 'initial' (default CSS value)
+    - 0 -> '0'
+    - ints and string representations of ints are interpreted as pixels.
+
+    Everything else is returned unchanged.
+    """
+    if val is None:
+        return 'initial'
+    elif str(val).isdigit():
+        return '0' if int(val) == 0 else '%spx' % val
+    return val
+
+
 def _slice_index(values, slices):
     # type: (List, int) -> Iterator[List]
     seq = list(values)
@@ -164,6 +183,7 @@ def init(self, builder, theme=None, dirs=None):
                                                 extensions=extensions)
         self.environment.filters['tobool'] = _tobool
         self.environment.filters['toint'] = _toint
+        self.environment.filters['todim'] = _todim
         self.environment.filters['slice_index'] = _slice_index
         self.environment.globals['debug'] = contextfunction(pformat)
         self.environment.globals['accesskey'] = contextfunction(accesskey)

sphinx/themes/agogo/static/agogo.css_t

@@ -269,7 +269,7 @@ div.document ol {
 /* Sidebar */
 
 div.sidebar {
-  width: {{ theme_sidebarwidth }};
+  width: {{ theme_sidebarwidth|todim }};
   float: right;
   font-size: .9em;
 }

sphinx/themes/basic/static/basic.css_t

@@ -49,7 +49,7 @@ div.sphinxsidebarwrapper {
 
 div.sphinxsidebar {
     float: left;
-    width: {{ theme_sidebarwidth|toint }}px;
+    width: {{ theme_sidebarwidth|todim }};
     margin-left: -100%;
     font-size: 90%;
     word-wrap: break-word;
@@ -199,6 +199,11 @@ table.modindextable td {
 
 /* -- general body styles --------------------------------------------------- */
 
+div.body {
+    min-width: {{ theme_body_min_width|todim }};
+    max-width: {{ theme_body_max_width|todim }};
+}
+
 div.body p, div.body dd, div.body li, div.body blockquote {
     -moz-hyphens: auto;
     -ms-hyphens: auto;

sphinx/themes/basic/theme.conf

@@ -7,4 +7,6 @@ sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
 [options]
 nosidebar = false
 sidebarwidth = 230
+body_min_width = 450
+body_max_width = 800
 navigation_with_keys = False

sphinx/themes/classic/static/classic.css_t

@@ -32,7 +32,7 @@ div.documentwrapper {
 }
 
 div.bodywrapper {
-    margin: 0 0 0 {{ theme_sidebarwidth|toint }}px;
+    margin: 0 0 0 {{ theme_sidebarwidth|todim }};
 }
 
 div.body {
@@ -43,7 +43,7 @@ div.body {
 
 {%- if theme_rightsidebar|tobool %}
 div.bodywrapper {
-    margin: 0 {{ theme_sidebarwidth|toint }}px 0 0;
+    margin: 0 {{ theme_sidebarwidth|todim }} 0 0;
 }
 {%- endif %}
 

sphinx/themes/haiku/static/haiku.css_t

@@ -34,8 +34,8 @@ body {
     margin: auto;
     padding: 0px;
     font-family: "DejaVu Sans", Arial, Helvetica, sans-serif;
-    min-width: 59em;
-    max-width: 70em;
+    min-width: {{ theme_body_min_width|todim }};
+    max-width: {{ theme_body_max_width|todim }};
     color: {{ theme_textcolor }};
 }
 

sphinx/themes/haiku/theme.conf

@@ -5,6 +5,8 @@ pygments_style = autumn
 
 [options]
 full_logo         = false
+body_min_width    = 59em
+body_max_width    = 70em
 textcolor         = #333333
 headingcolor      = #0c3762
 linkcolor         = #dc3c01

sphinx/themes/nature/static/nature.css_t

@@ -28,7 +28,7 @@ div.documentwrapper {
 }
 
 div.bodywrapper {
-    margin: 0 0 0 {{ theme_sidebarwidth|toint }}px;
+    margin: 0 0 0 {{ theme_sidebarwidth|todim }};
 }
 
 hr {

sphinx/themes/pyramid/static/pyramid.css_t

@@ -28,7 +28,7 @@ div.documentwrapper {
 }
 
 div.bodywrapper {
-    margin: 0 0 0 {{ theme_sidebarwidth }}px;
+    margin: 0 0 0 {{ theme_sidebarwidth|todim }};
 }
 
 hr {
@@ -92,7 +92,7 @@ div.related a {
 }
 
 div.related ul {
-    padding-left: {{ theme_sidebarwidth|toint + 10 }}px;
+    padding-left: calc({{ theme_sidebarwidth|todim }} + 10px);
 }
 
 div.sphinxsidebar {

sphinx/themes/scrolls/static/scrolls.css_t

@@ -98,7 +98,8 @@ h1.heading span {
 }
 
 #contentwrapper {
-    max-width: 680px;
+    min-width: {{ theme_body_min_width|todim }};
+    max-width: {{ theme_body_max_width|todim }};
     padding: 0 18px 20px 18px;
     margin: 0 auto 0 auto;
     border-right: 1px solid #eee;

sphinx/themes/scrolls/theme.conf

@@ -4,6 +4,8 @@ stylesheet = scrolls.css
 pygments_style = tango
 
 [options]
+body_min_width = 0
+body_max_width = 680
 headerbordercolor = #1752b4
 subheadlinecolor  = #0d306b
 linkcolor         = #1752b4

sphinx/themes/sphinxdoc/static/sphinxdoc.css_t

@@ -38,7 +38,7 @@ div.document {
 }
 
 div.bodywrapper {
-    margin: 0 {{ theme_sidebarwidth|toint + 10 }}px 0 0;
+    margin: 0 calc({{ theme_sidebarwidth|todim }} + 10px) 0 0;
     border-right: 1px solid #ccc;
 }
 
@@ -88,7 +88,7 @@ div.sphinxsidebarwrapper {
 div.sphinxsidebar {
     margin: 0;
     padding: 0.5em 15px 15px 0;
-    width: {{ theme_sidebarwidth|toint - 20 }}px;
+    width: calc({{ theme_sidebarwidth|todim }} - 20px);
     float: right;
     font-size: 1em;
     text-align: left;

sphinx/themes/traditional/static/traditional.css_t

@@ -23,10 +23,12 @@ div.documentwrapper {
 }
 
 div.bodywrapper {
-    margin: 0 {{ theme_sidebarwidth }}px 0 0;
+    margin: 0 {{ theme_sidebarwidth|todim }} 0 0;
 }
 
 div.body {
+    min-width: {{ theme_body_min_width|todim }};
+    max-width: {{ theme_body_max_width|todim }};
     background-color: white;
     padding: 0 20px 30px 20px;
 }
@@ -40,7 +42,7 @@ div.sphinxsidebarwrapper {
 div.sphinxsidebar {
     float: right;
     margin-left: -100%;
-    width: {{ theme_sidebarwidth }}px;
+    width: {{ theme_sidebarwidth|todim }};
 }
 
 div.clearer {

sphinx/themes/traditional/theme.conf

@@ -1,3 +1,7 @@
 [theme]
 inherit = basic
 stylesheet = traditional.css
+
+[options]
+body_min_width = 0
+body_max_width = none