Some doc improvements to highlight new functionality.

jdavidheiser · Mar 6, 2016 · f432ac8 · f432ac8
1 parent 1b8defb
commit f432ac8
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 21 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/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
@@ -165,10 +165,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 3. Now render with qgrid again, and tweak some options\n",
+    "### 3. 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/).\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,7 +184,7 @@
    },
    "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})"
    ]
   },
   {
@@ -198,7 +198,7 @@
    "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,8 @@
    "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.  If you're an advanced user you might be interested in constructing the QGridWidget directly, so that you can retrieve or update the DataFrame it uses internally."
    ]
   },
   {
@@ -258,8 +259,38 @@
    },
    "outputs": [],
    "source": [
-    "qgrid.show_grid(df2)"
+    "from IPython.display import display\n",
+    "grid = qgrid.QGridWidget(df=df2)\n",
+    "display(grid)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 3. 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``."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "grid.df"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {