Add support for generating margin and full-width figures.

Classes such as tufte-book support placing figures in the margin notes,
as well as full-width figures which span the main text and the margin
notes. This commit adds support for generating such figures.

Author: bcbnz

doc/config.md

@@ -47,6 +47,8 @@ The default settings for the ``tex`` section are as follows:
 engine = xelatex
 text_width = 345 points
 text_height = 550 points
+marginpar_width = 65 points
+marginpar_sep = 11 points
 num_columns = 1
 columnsep = 10 points
 ```
@@ -74,6 +76,11 @@ dimensions of a TeX document can be measured using the `layouts` package:
 
 This prints a diagram in the output document showing the dimensions.
 
+The `marginpar_width` and `marginpar_sep` refer to the width of the margin
+notes and the separator between the main text area and the margin notes. They
+are used when generating figures which fit in the margin notes, or which span
+the main text area and the margin notes.
+
 The number of columns and the width of the separators between them are only
 used when generating figures for multiple-column documents.
 

doc/usage.md

@@ -98,6 +98,45 @@ now results in a 4 inch wide figure (i.e., 80% of the 5 inches that would make
 up a full two columns).
 
 
+Margin figures and full-width figures
+-------------------------------------
+
+Some LaTeX document classes (e.g., those in the [Tufte-LaTeX][1] project) have
+the option to place figures in the margin notes. To generate a figure to fit
+within the margin, make sure the `marginpar_width` parameter in your
+[configuration](config.md) is correct, and pass `margin=True` when calling the
+`setup_figure()` function:
+
+```python
+setup_figure(height=0.2, margin=True)
+```
+
+This will result in a figure that spans the margin and is 20% of the text
+height. If a floating point number is given to the `width` parameter, this is
+interpreted relative to the margin width, i.e., to create a figure spanning 80%
+of the margin:
+
+```python
+setup_figure(width=0.8, height=0.2, margin=True)
+```
+
+It is sometimes desirable to create a figure spanning the full width of such a
+document, i.e., the main text area, the margin notes, and any separator between
+them. To do this, make sure the `marginpar_width` and `marginpar_sep` values in
+your [configuration](config.md) are correct, and pass `full_width=True` when
+calling the setup function:
+
+```python
+setup_figure(height=0.3, full_width=True)
+```
+
+Again, a fractional width is interpreted relative to the full width.
+
+If `full_width=True`, then the values of the `margin` and `columns` parameters
+are ignored. Similarly, if `margin=True` and `full_width=False`, then the value
+of `columns` is ignored.
+
+
 Saving
 ------
 

extras/pgfutils.cfg

@@ -41,6 +41,8 @@ engine = xelatex
 # without a unit is assumed to be inches, the default unit of Matplotlib.
 text_width = 345 points
 text_height = 550 points
+marginpar_width = 65 points
+marginpar_sep = 11 points
 
 # For multi-column layouts.
 num_columns = 1

pgfutils.py

@@ -348,6 +348,8 @@ def _config_reset():
            'engine': 'xelatex',
            'text_width': '345 points',
            'text_height': '550 points',
+           'marginpar_width': '65 points',
+           'marginpar_sep': '11 points',
            'num_columns': '1',
            'columnsep': '10 points',
         },
@@ -495,7 +497,8 @@ def _list_opened_files():
 _interactive = False
 
 
-def setup_figure(width=1.0, height=1.0, columns=None, **kwargs):
+def setup_figure(width=1.0, height=1.0, columns=None, margin=False,
+                 full_width=False, **kwargs):
     """Set up matplotlib figures for PGF output.
 
     This function should be imported and run before you import any matplotlib
@@ -504,16 +507,28 @@ def setup_figure(width=1.0, height=1.0, columns=None, **kwargs):
 
     Parameters
     ----------
-    width, height: float or string
+    width, height : float or string
         If a float, the fraction of the corresponding text width or height that
         the figure should take up. If a string, a dimension in centimetres
         (cm), millimetres (mm), inches (in) or points (pt). For example, '3in'
         or '2.5 cm'.
-    columns: integer, optional
+    columns : integer, optional
         The number of columns the figure should span. This should be between 1
         and the total number of columns in the document (as specified in the
         configuration). A value of None corresponds to spanning all columns.
         Any other value results in a ValueError being raised.
+    margin : Boolean, default False
+        If True, a margin figure (i.e., one to fit within the margin notes in
+        the document) is generated. If the width is a fraction, it is treated
+        as a fraction of the marginpar_width configuration setting. The height
+        is still treated as a fraction of the text height. The columns setting
+        is ignored if this is True.
+    full_width : Boolean, default False
+        If True, a full-width figure, i.e., one spanning the main text, the
+        margin notes, and the separator between them, is generated. A
+        fractional width is treated relative to the full width. The height is
+        still treated as a fraction of the text height. The columns and margin
+        parameters are ignored if this is True.
 
     """
     global _config, _interactive
@@ -620,10 +635,20 @@ def setup_figure(width=1.0, height=1.0, columns=None, **kwargs):
     # the width corresponding to the figure parameter being 1.
     # First, look up some document properties.
     text_width = _config['tex'].getdimension('text_width')
+    margin_width = _config['tex'].getdimension('marginpar_width')
+    margin_sep = _config['tex'].getdimension('marginpar_sep')
     num_columns = _config['tex'].getint('num_columns')
 
+    # Full-width figure.
+    if full_width:
+        available_width = text_width + margin_sep + margin_width
+
+    # Making a margin figure.
+    elif margin:
+        available_width = margin_width
+
     # Columns not specified, or spanning all available.
-    if columns is None or columns == num_columns:
+    elif columns is None or columns == num_columns:
         available_width = text_width
 
     # More columns than present in the document.

tests/test_setup_figure.py

@@ -158,3 +158,83 @@ def test_kwargs_rejects_unknown(self):
         """Test setup_figure() rejects unknown configuration options..."""
         with raises(KeyError):
             setup_figure(width=1, height=1, border_width=3)
+
+
+    def test_setup_margin(self):
+        """Test setup_figure() generates margin figures with margin=True..."""
+        setup_figure()
+        margin = _config['tex'].getdimension('marginpar_width')
+        height = _config['tex'].getdimension('text_height')
+
+        # Fractional tests.
+        for w_in in {1.0, 0.5, 1.2}:
+            for h_in in {0.3, 0.25, 0.5}:
+                _config_reset()
+                setup_figure(width=w_in, height=h_in, margin=True)
+                w, h = matplotlib.rcParams['figure.figsize']
+                assert w == approx(w_in * margin)
+                assert h == approx(h_in * height)
+
+        # Specific size.
+        _config_reset()
+        setup_figure(width="1.8in", height="1.2in", margin=True)
+        w, h = matplotlib.rcParams['figure.figsize']
+        assert w == approx(1.8)
+        assert h == approx(1.2)
+
+
+    def test_setup_full_width(self):
+        """Test setup_figure() generates full-width figures with full_width=True..."""
+        setup_figure()
+        text = _config['tex'].getdimension('text_width')
+        sep = _config['tex'].getdimension('marginpar_sep')
+        margin = _config['tex'].getdimension('marginpar_width')
+        full = text + sep + margin
+        height = _config['tex'].getdimension('text_height')
+
+        # Fractional tests.
+        for w_in in {1.0, 0.75, 1.1}:
+            for h_in in {0.4, 0.35, 0.15}:
+                _config_reset()
+                setup_figure(width=w_in, height=h_in, full_width=True)
+                w, h = matplotlib.rcParams['figure.figsize']
+                assert w == approx(w_in * full)
+                assert h == approx(h_in * height)
+
+        # Specific size.
+        _config_reset()
+        setup_figure(width="5.5in", height="3.6in", full_width=True)
+        w, h = matplotlib.rcParams['figure.figsize']
+        assert w == approx(5.5)
+        assert h == approx(3.6)
+
+
+    def test_setup_arg_priority(self):
+        """Test priority of columns/margin/full_width arguments to setup_figure()..."""
+        setup_figure()
+        text = _config['tex'].getdimension('text_width')
+        sep = _config['tex'].getdimension('marginpar_sep')
+        margin = _config['tex'].getdimension('marginpar_width')
+        full = text + sep + margin
+        height = _config['tex'].getdimension('text_height')
+
+        # All three: full width should take priority.
+        _config_reset()
+        setup_figure(width=1, height=0.4, columns=1, margin=True, full_width=True)
+        w, h = matplotlib.rcParams['figure.figsize']
+        assert w == approx(full)
+        assert h == approx(0.4 * height)
+
+        # Margin and full width: full width should take priority.
+        _config_reset()
+        setup_figure(width=1, height=0.4, margin=True, full_width=True)
+        w, h = matplotlib.rcParams['figure.figsize']
+        assert w == approx(full)
+        assert h == approx(0.4 * height)
+
+        # Margin and columns: margin should take priority.
+        _config_reset()
+        setup_figure(width=1, height=0.4, columns=1, margin=True)
+        w, h = matplotlib.rcParams['figure.figsize']
+        assert w == approx(margin)
+        assert h == approx(0.4 * height)