DOC: Show how Pandas dataframes can be displayed

Author: mgeier

.travis.yml

@@ -27,7 +27,9 @@ install:
   - pip install Sphinx$SPHINX
   - pip install .
   - pip install ipykernel
+  - pip install numpy
   - pip install matplotlib
+  - pip install pandas
   - pip install sphinxcontrib-bibtex
 script:
   - python -m sphinx doc/ doc/_build/ -b html

doc/code-cells.ipynb

@@ -160,9 +160,7 @@
    "source": [
     "## Special Display Formats\n",
     "\n",
-    "See [IPython example notebook](https://nbviewer.jupyter.org/github/ipython/ipython/blob/master/examples/IPython Kernel/Rich Output.ipynb).\n",
-    "\n",
-    "TODO: tables? e.g. Pandas DataFrame?"
+    "See [IPython example notebook](https://nbviewer.jupyter.org/github/ipython/ipython/blob/master/examples/IPython Kernel/Rich Output.ipynb)."
    ]
   },
   {
@@ -402,6 +400,115 @@
     "fig"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Pandas Dataframes\n",
+    "\n",
+    "[Pandas dataframes](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe)\n",
+    "should be displayed as nicely formatted HTML tables (if you are using HTML output)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import pandas as pd"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.DataFrame(np.random.randint(0, 100, size=[5, 4]),\n",
+    "                  columns=['a', 'b', 'c', 'd'])\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For LaTeX output, however, the plain text output is used by default.\n",
+    "\n",
+    "To get nice LaTeX tables, a few settings have to be changed:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pd.set_option('display.latex.repr', True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is not enabled by default because of\n",
+    "[Pandas issue #12182](https://github.com/pandas-dev/pandas/issues/12182).\n",
+    "\n",
+    "The generated LaTeX tables utilize the `booktabs` package, so you have to make sure that package is [loaded in the preamble](http://www.sphinx-doc.org/en/master/latex.html) with:\n",
+    "\n",
+    "    \\usepackage{booktabs}\n",
+    "\n",
+    "In order to allow page breaks within tables, you should use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pd.set_option('display.latex.longtable', True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `longtable` package is already used by Sphinx,\n",
+    "so you don't have to manually load it in the preamble.\n",
+    "\n",
+    "Finally, if you want to use LaTeX math expressions in your dataframe, you'll have to disable escaping:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pd.set_option('display.latex.escape', False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above settings should have no influence on the HTML output, but the LaTeX output should now look nicer:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.DataFrame(np.random.randint(0, 100, size=[10, 4]),\n",
+    "                  columns=[r'$\\alpha$', r'$\\beta$', r'$\\gamma$', r'$\\delta$'])\n",
+    "df"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

doc/conf.py

@@ -143,6 +143,7 @@
 }{
     \renewcommand{\ttdefault}{lmtt}  % typewriter font from lmodern
 }
+\usepackage{booktabs}  % for Pandas dataframes
 """,
 }
 

doc/readthedocs-environment.yml

@@ -6,5 +6,7 @@ dependencies:
   - pandoc
   - nbconvert!=5.4
   - ipykernel
+  - numpy
   - matplotlib
+  - pandas
   - sphinxcontrib-bibtex

doc/requirements.txt

@@ -1,5 +1,7 @@
 sphinx>=1.6
 nbconvert!=5.4
 ipykernel
+numpy
 matplotlib
+pandas
 sphinxcontrib-bibtex