Merge pull request quantopian#61 from quantopian/fix-docs

Fix docs
jdavidheiser · Feb 16, 2016 · a82d761 · a82d761
2 parents 9f9c5e0 + bf1c28b
commit a82d761
Show file tree

Hide file tree

Showing 5 changed files with 672 additions and 17 deletions.
diff --git a/README.rst b/README.rst
@@ -29,6 +29,10 @@ Demo
 See the demo by viewing `qgrid_demo.ipynb
 <http://nbviewer.jupyter.org/gist/TimShawver/2600c6648c6aaccaf3bf>`_ in nbviewer.
 
+API Documentation
+-----------------
+API documentation is hosted on `readthedocs <http://qgrid.readthedocs.org/en/latest/>`_.
+
 Installation
 ------------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,8 +3,26 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-qgrid API Documentation
-=================================
+Qgrid API Documentation
+=======================
+
+Qgrid is an `IPython widget <https://github.com/ipython/ipywidgets>`_ which uses
+`SlickGrid <https://github.com/mleibman/SlickGrid>`_ to render `pandas <https://github.com/pydata/pandas>`_ DataFrames
+within a `Jupyter notebook <https://github.com/jupyter/notebook>`_.
+
+Other qgrid resources
+--------------------
+
+This page hosts only the API docs for the project.  You might also be interested in these other qgrid-related
+resources:
+
+`qgrid on GitHub <https://github.com/quantopian/qgrid>`_
+  This is where you'll find the source code and the rest of the documentation for the project, including the
+  instructions for installing and running qgrid.
+
+`qgrid demo on nbviewer <http://nbviewer.jupyter.org/gist/TimShawver/2600c6648c6aaccaf3bf>`_
+  See a demo of qgrid in your browser without installing anything.  The functionality of qgrid is somewhat limited
+  in this environment, but it'll give you an idea of how the grid will look and feel when you install it locally.
 
 :mod:`qgrid` Module
 -------------------

diff --git a/qgrid/grid.py b/qgrid/grid.py
@@ -124,16 +124,13 @@ def set_grid_option(optname, optvalue):
     defaults.grid_options[optname] = optvalue
 
 
-def show_grid(data_frame, show_toolbar=False, remote_js=None, precision=None,
-              grid_options=None):
+def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
+              show_toolbar=False):
     """
     Main entry point for rendering DataFrames as SlickGrids.
 
     Parameters
     ----------
-    show_toolbar: bool
-        Whether to show a toolbar with options for adding/removing rows and
-        exporting the widget to a static view.
     remote_js : bool
         Whether to load slickgrid.js from a local filesystem or from a
         remote CDN.  Loading from the local filesystem means that SlickGrid
@@ -145,10 +142,14 @@ def show_grid(data_frame, show_toolbar=False, remote_js=None, precision=None,
         values.  If unset, we use the value of
         `pandas.get_option('display.precision')`.
     grid_options : dict
-        Options to use when creating javascript SlickGrid instances.  See
-        the `SlickGrid documentation <https://github.com/mleibman/SlickGrid/wiki/Grid-Options>`_ for
-        information on the available options.  See the Notes section below for
-        the list of options that qgrid sets by default.
+        Options to use when creating javascript SlickGrid instances.  See the Notes section below for
+        more information on the available options, as well as the default options that qgrid uses.
+    show_toolbar : bool
+        *EXPERIMENTAL* - Whether to show a toolbar with options for adding/removing rows and
+        exporting the widget to a static view.  This feature is marked as experimental because
+        add/remove rows is not fully functional yet.  The export feature should work fine,
+        so it's technically not experimental.  Most people will have no need for it though, so
+        I don't mind keeping it buried here under the experimental label.
 
     Notes
     -----

diff --git a/qgrid_demo.ipynb b/qgrid_demo.ipynb
@@ -81,9 +81,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Interactive Tutorial - Editing a DataFrame returned by Yahoo Finance\n",
-    "\n",
-    "The cells in this section will walk you through a series of function calls that will demonstrate qgrid's features.\n",
+    "## Example 1 - Render a DataFrame returned by Yahoo Finance\n",
     "\n",
     "### 1. Create a sample DataFrame using pandas 'get_data_yahoo' function"
    ]
@@ -167,9 +165,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 4. Show the add/remove row buttons and set some grid_options\n",
+    "### 3. Now render with qgrid again, and tweak some options\n",
     "The `show_grid` function takes a number of optional parameters to allow you to configure the behavior of the grid it generates.  In the following example we use a couple of these optional parameters:\n",
-    "* `show_toolbar` takes a boolean and defaults to False.   When set to True, a toolbar gets shown on top of the grid with some useful editing controls.  If you're viewing this notebook on nbviewer, those editing controls won't be visible.\n",
+    "\n",
+    "* `precision` is the number of digits of precision to display for floating-point values. If unset, we use the value of pandas.get_option(‘display.precision’).\n",
     "* `grid_options` takes a dict and allows you to pass any of the \"grid options\" listed in [SlickGrid's documentation](https://github.com/mleibman/SlickGrid/wiki/Grid-Options).  In this example we make use of two of these options, `forceFitColumns` and `defaultColumnWidth`, to improve qgrid's ability to handle a large number of columns\n",
     "\n",
     "You can read about these and the rest of the optional parameters for the `show_grid` function in our [API documentation](http://qgrid.readthedocs.org/en/latest/#qgrid.show_grid).  \n",
@@ -185,7 +184,81 @@
    },
    "outputs": [],
    "source": [
-    "qgrid.show_grid(spy, show_toolbar=True, grid_options={'forceFitColumns': False, 'defaultColumnWidth': 200})"
+    "qgrid.show_grid(spy, precision=2, grid_options={'forceFitColumns': False, 'defaultColumnWidth': 200})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "*The same 'spy' DataFrame rendered as a qgrid again, this time some options tweaked.  Precision has been decreased to 2, the columns are wider, and a horizontal scroll bar has appeared.*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 2 - Rendering a grid containing some different data types"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 1. Create a new sample DataFrame "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "df2 = pd.DataFrame({\n",
+    "    'A' : 1.,\n",
+    "    'B' : pd.Timestamp('20130102'),\n",
+    "    'C' : pd.Series(randn(8),index=list(range(8)),dtype='float32'),\n",
+    "    'D' : np.array([3] * 8,dtype='int32'),\n",
+    "    'E' : pd.Categorical([\"test\",\"train\",\"test\",\"train\", \"test\", \"train\", \"test\", \"train\"]),\n",
+    "    'F' : 'foo' })"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 2. Render the DataFrame without using qgrid"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "df2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 3. Render the DataFrame again, this time using qgrid"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "qgrid.show_grid(df2)"
    ]
   }
  ],