Merge pull request quantopian#67 from quantopian/doc-cleanup

Doc cleanup
jdavidheiser · Mar 6, 2016 · ea6359a · ea6359a
2 parents e1190ae + 275f415
commit ea6359a
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 34 deletions.
diff --git a/README.rst b/README.rst
@@ -64,8 +64,17 @@ want.  To run the latest code that is on master, install qgrid from GitHub inste
 
     pip install git+https://github.com/quantopian/qgrid
 
-Running the demo locally
---------------------------
+Running the demo notebook locally
+---------------------------------
+
+The qgrid repository includes a demo notebook which will help you get familiar with the functionality that qgrid
+provides.  This demo notebook doesn't get downloaded to your machine when you install qgrid with pip, so you'll need
+to clone the qgrid repository to get it.  Here are the steps to clone the repository and run the demo notebook:
+
+#. Clone the repository from GitHub and ``cd`` into it the top-level directory::
+
+    git clone https://github.com/quantopian/qgrid.git
+    cd qgrid
 
 #. Go to the top-level directory of the qgrid repository and run the notebook::
 
@@ -84,7 +93,7 @@ Running the demo locally
          The "notebook dashboard" for the jupyter notebook which shows all the files in the current directory.  Notice
          the demo notebook which is qgrid_demo.ipynb.
 
-#. Click on qgrid_demo.ipynb to open it.  Here's what that will should like:
+#. Click on qgrid_demo.ipynb to open it.  Here's what that should like:
 
      .. figure:: docs/images/notebook_screen.png
          :align: left
@@ -93,8 +102,16 @@ Running the demo locally
 
          The demo notebook, qgrid_demo.ipynb, rendered by a locally-running Jupyter notebook.
 
-#. Skip to the Notebook Installation section of the notebook because the Overview is copied from this document.
-   Read the text and execute the cells as you come to them to complete the demo.
+#. Click the "Cell" menu at the top of the notebook and click "Run All" to run all the cells in the notebook and
+   render a few sample qgrids.
+
+        .. figure:: docs/images/qgrid_screen.png
+         :align: left
+         :target: docs/images/qgrid_screen.png
+         :width: 800px
+
+         A sample qgrid, as seen in the demo notebook, qgrid_demo.ipynb.
+
 
 Running from source
 -------------------
@@ -119,15 +136,6 @@ to do this.
    the ``pip install -e``.  The result is changes that you make to the source code will be reflected as soon as you restart
    the notebook.
 
-   If you have virtualenv and virtualenvwrapper installed, an easy way to verify that this "editable" install succeeded
-   is to do the following::
-
-    cdsitepackages # navigate to the directory where virtualenv installs packages
-    cat qgrid.egg-link # print out the contents of this symbolic link
-
-   You should find that the symbolic link points to the top level directory of the qgrid repository which you ran
-   the ``pip install -e`` command on.
-
 #. Follow the instructions in the previous section to run qgrid.  Now when you make changes to qgrid's Python code,
    those changes will take effect as soon as you restart the Jupyter notebook server.
 

diff --git a/docs/images/qgrid_screen.png b/docs/images/qgrid_screen.png
diff --git a/qgrid/grid.py b/qgrid/grid.py
@@ -50,20 +50,27 @@ def __init__(self):
             'editable': True,
             'autoEdit': False
         }
+        self._show_toolbar = False
         self._remote_js = False
         self._precision = None  # Defer to pandas.get_option
 
     def set_grid_option(self, optname, optvalue):
         self._grid_options[optname] = optvalue
 
-    def set_defaults(self, remote_js=None, precision=None, grid_options=None):
+    def set_defaults(self, show_toolbar=None, remote_js=None, precision=None, grid_options=None):
+        if show_toolbar is not None:
+            self._show_toolbar = show_toolbar
         if remote_js is not None:
             self._remote_js = remote_js
         if precision is not None:
             self._precision = precision
         if grid_options is not None:
             self._grid_options = grid_options
 
+    @property
+    def show_toolbar(self):
+        return self._show_toolbar
+
     @property
     def grid_options(self):
         return self._grid_options
@@ -79,7 +86,7 @@ def precision(self):
 defaults = _DefaultSettings()
 
 
-def set_defaults(remote_js=None, precision=None, grid_options=None):
+def set_defaults(show_toolbar=None, remote_js=None, precision=None, grid_options=None):
     """
     Set the default qgrid options.  The options that you can set here are the
     same ones that you can pass into ``show_grid``.  See the documentation
@@ -98,7 +105,7 @@ def set_defaults(remote_js=None, precision=None, grid_options=None):
     show_grid :
         The function whose default behavior is changed by ``set_defaults``.
     """
-    defaults.set_defaults(remote_js, precision, grid_options)
+    defaults.set_defaults(show_toolbar, remote_js, precision, grid_options)
 
 
 def set_grid_option(optname, optvalue):
@@ -124,13 +131,18 @@ def set_grid_option(optname, optvalue):
     defaults.grid_options[optname] = optvalue
 
 
-def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
-              show_toolbar=False):
+def show_grid(data_frame, show_toolbar=None, remote_js=None, precision=None, grid_options=None):
     """
     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.  Adding/removing rows only works with
+        DataFrames that have an integer index.  The export feature is used to
+        generate a copy of the grid that will be mostly functional when rendered in
+        nbviewer.jupyter.org or when exported to html via the notebook's File menu.
     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
@@ -144,12 +156,6 @@ def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
     grid_options : dict
         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
     -----
@@ -176,6 +182,8 @@ def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
     set_grid_option : Permanently set individual SlickGrid options.
     """
 
+    if show_toolbar is None:
+        show_toolbar = defaults.show_toolbar
     if remote_js is None:
         remote_js = defaults.remote_js
     if precision is None:

diff --git a/qgrid/qgridjs/qgrid.css b/qgrid/qgridjs/qgrid.css
@@ -159,7 +159,7 @@
   height: 28px;
   width: 21px;
   text-align: center;
-  z-index: 900;
+  z-index: 10;
   background-image: none;
   margin-top: 0px;
 }

diff --git a/qgrid_demo.ipynb b/qgrid_demo.ipynb
@@ -53,7 +53,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -165,10 +165,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 3. Now render with qgrid again, and tweak some options\n",
+    "### 4. Now render with qgrid again, and set 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",
     "\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",
+    "* Setting `show_toolbar` to True causes some buttons to be shown above the grid.  These buttons allow you to add and remove rows, as well as export a version of qgrid that will be functional when rendered by [nbviewer](http://nbviewer.jupyter.org/).  Note that these buttons won't be visible on nbviewer.jupyter.org, only when qgrid is running within a jupyter notebook.\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",
@@ -184,21 +184,21 @@
    },
    "outputs": [],
    "source": [
-    "qgrid.show_grid(spy, precision=2, grid_options={'forceFitColumns': False, 'defaultColumnWidth': 200})"
+    "qgrid.show_grid(spy, show_toolbar=True, 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.*"
+    "*The same 'spy' DataFrame rendered as a qgrid again, this time some options tweaked.  The toolbar buttons are visible, 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"
+    "## Example 2 - Rendering a grid by creating a QGridWidget"
    ]
   },
   {
@@ -247,7 +247,29 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 3. Render the DataFrame again, this time using qgrid"
+    "### 3. Render the DataFrame again, this time using the QGridWidget class directly\n",
+    "The ``show_grid`` function is just a convenience function which internally constructs an instance of QGridWidget and renders it with jupyter notebook's ``display`` function.  The following code shows how to construct a QGridWidget directly, so that you can retrieve or update the DataFrame it uses internally."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from IPython.display import display\n",
+    "grid = qgrid.QGridWidget(df=df2)\n",
+    "display(grid)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 4. Get the DataFrame back from the QGridWidget and render it without qgrid\n",
+    "If you make edits to the data using the grid above, they will be reflected in the DataFrame that is returned by ``grid.df``."
    ]
   },
   {
@@ -258,7 +280,7 @@
    },
    "outputs": [],
    "source": [
-    "qgrid.show_grid(df2)"
+    "grid.df"
    ]
   }
  ],