ENH: Styler.to_latex conversion from CSS

doc/source/user_guide/style.ipynb

@@ -1792,6 +1792,135 @@
     "See the template in the [GitHub repo](https://github.com/pandas-dev/pandas) for more details."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## LaTeX\n",
+    "\n",
+    "Since version XXX Styler has an alternative jinja2 template and additional parsing functions to allow it to produce conditionally styled LaTeX tables.\n",
+    "\n",
+    "The above HTML-CSS representation in terms of `(<attribute>, <value>)` pairs is effectively replaced by a LaTeX `(<command>, <options>)` format, and renders styles directly to each cell in a nested format. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df5 = pd.DataFrame([[1, 2.2, \"dogs\"], [3, 4.4, \"cats\"], [2, 6.6, \"cows\"]], \n",
+    "                   index=[\"ix1\", \"ix2\", \"ix3\"], \n",
+    "                   columns=[\"Integers\", \"Floats\", \"Strings\"])\n",
+    "df5"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For example we can style the above DataFrame using the normal functions but modifying our ``props`` argument to the LaTeX format. In this example the coloring commands have options but the text modifying commands do not need any. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s5 = df5.style.highlight_max(props='cellcolor:[HTML]{FFFF00}; color:{red}; itshape:; bfseries:;')\n",
+    "print(s5.to_latex())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![LaTeX Styler example 1](../_static/style/latex_1.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When specifying the ``options`` there are 5 hidden flags that can be amended to structure the braces used in LaTeX output:\n",
+    "\n",
+    " - ``--nowrap`` which is the default produces: ``\\<command><options> <display_value>``\n",
+    " - ``--wrap`` encloses the whole block in braces: ``{\\<command><options> <display_value>}``\n",
+    " - ``--lwrap`` encloses the left block in braces: ``{\\<command><options>} <display_value>``\n",
+    " - ``--rwrap`` encloses the right block in braces: ``\\<command><options>{<display_value>}``\n",
+    " - ``--dwrap`` encloses both blocks in braces: ``{\\<command><options>}{<display_value>}``\n",
+    " \n",
+    "For example the \\textbf and \\bfseries and the \\textit and \\itshape alternatives should be structured in different formats. We can replicate the above LaTeX render in these alternatives as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s5 = df5.style.highlight_max(props='cellcolor:[HTML]{FFFF00}; color:{red}; textit:--rwrap; textbf:--rwrap;')\n",
+    "\n",
+    "print(s5.to_latex())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The ``to_latex`` method provides a number of options for the LaTeX output such as:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df5.columns = pd.MultiIndex.from_tuples([(\"Numeric\", \"Integers\"), (\"Numeric\", \"Floats\"), (\"Non-Numeric\", \"Strings\")])\n",
+    "df5.index = pd.MultiIndex.from_tuples([(\"L0\", \"ix1\"), (\"L0\", \"ix2\"), (\"L1\", \"ix3\")])\n",
+    "s5 = df5.style.highlight_max(props='cellcolor:[HTML]{FFFF00}; color:{red}; itshape:; bfseries:;')\n",
+    "\n",
+    "print(s5.to_latex(column_format=\"rrrrr\", position=\"h\", position_float=\"centering\", hrules=True, \n",
+    "                  label=\"table:5\", caption=\"Styled LaTeX Table\", multirow_align=\"t\", multicol_align=\"r\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![LaTeX Styler example 2](../_static/style/latex_2.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A difference to the ``DataFrame.to_latex()`` method is that LaTeX Styler version does not contain any options for formatting. Instead, the usual ``.format()`` method should be used to create the display values before rendering. There are three good reasons for making this change:\n",
+    "\n",
+    " - Firstly using ``.format()`` in a Jupyter Notebook allows you to visualise the results of the formatting application before rendering.\n",
+    " - Secondly the ``.format()`` is very flexible and by chaining the method multiple times gives an even broader array of formatting possibilities which it is not possible to replicate by including the arguments in the ``to_latex()`` method which will call ``.format()`` a single time.\n",
+    " - Thirdly the ``.format()`` method has multiple options and updating the ``to_latex()`` method whenever ``.format()`` is updated or improved creates a development dependency which is best avoided."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s5.clear()\n",
+    "s5.table_styles = []\n",
+    "s5.caption = None\n",
+    "s5.format({\n",
+    "    (\"Numeric\", \"Integers\"): '\\${}',\n",
+    "    (\"Numeric\", \"Floats\"): '{:.3f}',\n",
+    "    (\"Non-Numeric\", \"Strings\"): str.upper\n",
+    "})\n",
+    "print(s5.to_latex())"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

pandas/io/formats/style.py

@@ -341,33 +341,41 @@ def to_latex(
             Buffer to write to. If ``None``, the output is returned as a string.
         column_format : str, optional
             The LaTeX column specification placed in location:
-            `\\begin{tabular}{<column_format>}`. Defaults to 'l' for index and
-            non-numeric data columns, otherwise 'r' (or 'S' if using {siunitx} package).
+
+            \\begin{tabular}{<column_format>}
+
+            Defaults to 'l' for index and
+            non-numeric data columns, otherwise 'r' (or 'S' if using the
+            {siunitx} package).
         position : str, optional
             The LaTeX positional argument (e.g. 'h!') for tables, placed in location:
-            `\\begin{table}[<position>]`.
+
+            \\begin{table}[<position>]
         position_float : {"centering", "raggedleft", "raggedright"}, optional
-            The LaTeX float command (e.g. `\\centering`) placed immediately after
-            `\\begin{table}[<position>]`.
+            The LaTeX float command placed in location:
+
+            \\begin{table}[<position>]
+
+            \\<position_float>
         hrules : bool, default False
-            Set to `True` to add `\\toprule`, `\\midrule` and `\\bottomrule` from the
+            Set to `True` to add \\toprule, \\midrule and \\bottomrule from the
             {booktabs} LaTeX package.
         label : str, optional
-            The LaTeX label placed in location: `\\label{<label>}`.
-            This is used with `\\ref{<label>}` in the main .tex file.
+            The LaTeX label included as: \\label{<label>}.
+            This is used with \\ref{<label>} in the main .tex file.
         caption : str, optional
-            The LaTeX table caption placed in location: `\\caption{<caption>}`.
+            The LaTeX table caption included as: \\caption{<caption>}.
         sparsify : bool, optional
-            Set to `False` to print every item of a hierarchical MultiIndex. Defaults
-            to the pandas 'multi_sparse' display option.
+            Set to ``False`` to print every item of a hierarchical MultiIndex. Defaults
+            to the pandas ``multi_sparse`` display option.
         multirow_align : {"c", "t", "b"}
             If sparsifying hierarchical MultiIndexes whether to align text centrally,
             at the top or bottom.
         multicol_align : {"r", "c", "l"}
             If sparsifying hierarchical MultiIndex columns whether to align text at
             the left, centrally, or at the right.
         siunitx : bool, default False
-            Set to `True` to structure LaTeX compatible with the {siunitx} package.
+            Set to ``True`` to structure LaTeX compatible with the {siunitx} package.
         encoding : str, default "utf-8"
             Character encoding setting.
         convert_css : bool, default False
@@ -395,12 +403,20 @@ def to_latex(
 
         If using the ``siunitx`` argument then the necessary {siunitx} package should
         be included, and numeric columns will be set to format "S" instead of "r".
+        Additionally, if combining with \\itshape and \\bfseries we recommend the
+        {etoolbox} package in combination with the preamble commands:
+
+          - \\robustify\\itshape
+          - \\robustify\\bfseries
+
+        Also within the document, but before the {table} environment adding:
+
+          - \\sisetup{detect-all = true}
 
         **Cell Styles**
 
         LaTeX styling can only be rendered if the accompanying styling functions have
-        been constructed with appropriate LaTeX commands. Styler was designed and
-        is typically used to generate HTML with a CSS Styling language. All styling
+        been constructed with appropriate LaTeX commands. All styling
         functionality is built around the concept of a CSS ``(<attribute>, <value>)``
         pair, and this should be replaced by a LaTeX ``(<command>, <options>)``
         approach and each cell will be styled individually
@@ -422,48 +438,51 @@ def to_latex(
         Internally these structured LaTeX ``(<command>, <options>)`` pairs
         are translated to the
         ``display_value`` with the default structure:
-        ``\\<command><options> <display_value>``.
+        ``\<command><options> <display_value>``.
         Where there are multiple commands the latter is nested recursively, so that
         the above example highlighed cell is rendered as:
-        `\\color{red} \\itshape 4`.
+
+        \\color{red} \\itshape 4
 
         Occasionally this format does not suit the applied command, or
         combination of LaTeX packages that is in use, so additional flags can be
         added to the ``<options>`` to result in different positions of required
-        braces (the default being the same as `--npwrap`):
+        braces (the default being the same as `--nowrap`):
 
           - (<command>,<options>--nowrap): \\<command><options> <display_value>
           - (<command>,<options>--rwrap): \\<command><options>{<display_value>}
           - (<command>,<options>--wrap): {\\<command><options> <display_value>}
           - (<command>,<options>--lwrap): {\\<command><options>} <display_value>
           - (<command>,<options>--dwrap): {\\<command><options>}{<display_value>}
 
-        For example the `Large` or `Huge` commands for font-sizing
-        should always be used with `--wrap` so `'Huge: --wrap;'` will render a
-        working cell, wrapped with braces, as `'{\\Huge <display_value>}'`.
+        For example the `textbf` command for font-weight
+        should always be used with `--rwrap` so ``('textbf', '--rwrap')`` will render a
+        working cell, wrapped with braces, as '\\textbf{<display_value>}'.
 
         **Table Styles**
 
-        Internally Styler uses its ``table_styles`` to parse some of the options here.
-        All options except for ``caption`` are added in the following way:
+        Internally Styler uses the ``table_styles`` object to parse some of the
+        input arguments.
+        All commands arguments except for ``caption`` are added in the following way:
 
-        >>> s.set_table_styles([{'selector': 'command', 'props': ':options;'}],
+        >>> s.set_table_styles([{'selector': '<command>', 'props': ':<options>;'}],
         ...                    overwrite=False)
 
         For example, if setting a ``column_format``, this is internally recorded as:
 
         >>> s.set_table_styles([{'selector': 'column_format', 'props': ':rcll;'}],
         ...                    overwrite=False])
 
-        Since ``labels`` often include ':' but this is used as a CSS separator, there
-        is a character replacement, substituting ':' for '§', so a label of 'fig:item1'
-        is recorded as:
+        Note that since ``labels`` often include ':' but this is used as a
+        CSS separator, there is a character replacement,
+        substituting ':' for '§', so a label of 'fig:item1' is recorded as:
 
         >>> s.set_table_styles([{'selector': 'label', 'props': ':{fig§item1};'}],
         ...                    overwrite=False])
 
-        Any custom commands you add here are added above the '`\\begin{tabular}`' entry,
-        such as odd and even row coloring can be included with:
+        Any custom commands you add here are included and positioned immediately
+        above the '\\begin{tabular}' command. For example to add odd and
+        even row coloring, from the {colortbl} package, use:
 
         >>> s.set_table_styles([{'selector': 'rowcolors', 'props': ':{1}{pink}{red};'}],
         ...                    overwrite=False])