Update Lux Docs

doc/conf.py

@@ -63,7 +63,7 @@
     "sphinx_automodapi.automodsumm",
 ]
 
-autodoc_default_flags = ["members", "inherited-members"]
+autodoc_default_flags = ["members", "no-undoc-members"]
 autodoc_member_order = "groupwise"
 autosummary_generate = True
 numpydoc_show_class_members = False

doc/source/advanced/architecture.rst

@@ -80,4 +80,4 @@ Number of Dimensions       Number of Measures         Mark Type
 Executor
 ----------
 The data executor populates each Vis with a subset of the dataframe based on the specified intent. 
-You can learn more about executors in Lux `here <https://lux-api.readthedocs.io/en/dfapi/source/guide/executor.html>`_.
+You can learn more about executors in Lux `here <https://lux-api.readthedocs.io/en/latest/source/advanced/executor.html>`_.

doc/source/advanced/date.rst

@@ -98,7 +98,7 @@ Below we look at an example stocks dataset that also has `date` field with each
 
 .. code-block:: python
 	
-	df = pd.read_csv("../../lux/data/stocks.csv")
+	df = pd.read_csv("https://github.com/lux-org/lux-datasets/blob/master/data/stocks.csv?raw=true")
 
 	df.dtypes
 

doc/source/advanced/interestingness.rst

@@ -1,24 +1,24 @@
-**********************
+*******************************
 Interestingness Scoring
-**********************
+*******************************
 
 In Lux, recommended visualizations are scored and ranked based on their statistical properties. 
 Lux uses various standard metrics for determining how interesting a visualization is. 
 The choice of an interestingness metric is dependent on the chart type, as shown in the following table.
 
-+----------------+---------+------------------------------------------------------------------+
-| Chart Type     | Filter? | Function                                                         |
-+================+=========+==================================================================+
-| Bar/Line Chart | ✔       | :func:`lux.interestingness.interestingness.unevenness`           |
-|                +---------+------------------------------------------------------------------+
++----------------+---------+--------------------------------------------------------------------+
+| Chart Type     | Filter? | Function                                                           |
++================+=========+====================================================================+
+| Bar/Line Chart | ✔       | :func:`lux.interestingness.interestingness.unevenness`             |
+|                +---------+--------------------------------------------------------------------+
 |                | X       | :func:`lux.interestingness.interestingness.deviation_from_overall` |
-+----------------+---------+------------------------------------------------------------------+
-| Histogram      | ✔       | :func:`lux.interestingness.interestingness.skewness`             |
-|                +---------+------------------------------------------------------------------+
++----------------+---------+--------------------------------------------------------------------+
+| Histogram      | ✔       | :func:`lux.interestingness.interestingness.skewness`               |
+|                +---------+--------------------------------------------------------------------+
 |                | X       | :func:`lux.interestingness.interestingness.deviation_from_overall` |
-+----------------+---------+------------------------------------------------------------------+
-| Scatterplot    | ✔/X     | :func:`lux.interestingness.interestingness.monotonicity`         |
-+----------------+---------+------------------------------------------------------------------+
++----------------+---------+--------------------------------------------------------------------+
+| Scatterplot    | ✔/X     | :func:`lux.interestingness.interestingness.monotonicity`           |
++----------------+---------+--------------------------------------------------------------------+
 
 Bar Chart Interestingness
 =========================
@@ -30,7 +30,7 @@ Bar charts without filters: Unevenness
 
 A chart is scored higher if it is more uneven, indicating high variation 
 in the individual bar values in the chart. The score is computed based 
-on the difference between the value of the bar chart .. math::`V` and the flat uniform distribution .. math::`V_{flat}`.
+on the difference between the value of the bar chart :math:`V` and the flat uniform distribution :math:`V_{flat}`.
 The difference is captured via the Euclidean distance (L2 norm).
 
 
@@ -42,6 +42,7 @@ The difference is captured via the Euclidean distance (L2 norm).
 .. Example: "Occurrence" recommendation
 
 .. _barWithFilter:
+
 Bar charts with filters: Deviation from Overall
 -----------------------------------------------
 
@@ -77,6 +78,7 @@ The skewness is computed based on `scipy.stats.skew <https://docs.scipy.org/doc/
 
 
 .. _histoWithFilter:
+
 Histogram with filters: Deviation from overall
 -----------------------------------------------
 
@@ -91,9 +93,10 @@ The deviation measures how different is the filtered distribution from the overa
 .. Example: "Filter" recommendation where the intent only has 1 measure.
 
 Scatterplot Interestingness
-=========================
+==============================
 
 .. _scatter:
+
 Scatterplot: Monotonicity
 -----------------------------------
 

doc/source/getting_started/overview.rst

@@ -2,7 +2,7 @@
 Overview
 ********
 
-.. note:: You can follow along this tutorial in a Jupyter notebook. [`Github <https://github.com/lux-org/lux-binder/blob/master/tutorial/tutorial/0-overview.ipynb>`_] [`Binder <https://mybinder.org/v2/gh/lux-org/lux-binder/master?urlpath=tree/tutorial/0-overview.ipynb>`_]
+.. note:: You can follow along this tutorial in a Jupyter notebook. [`Github <https://github.com/lux-org/lux-binder/blob/master/tutorial/0-overview.ipynb>`_] [`Binder <https://mybinder.org/v2/gh/lux-org/lux-binder/master?urlpath=tree/tutorial/0-overview.ipynb>`_]
 
 This tutorial provides an overview of how you can use Lux in your data exploration workflow. 
 
@@ -25,8 +25,7 @@ Lux preserves the Pandas dataframe semantics -- which means that you can apply a
 
     df = pd.read_csv("lux/data/college.csv")
 
-Lux is built on the philosophy that generating useful visualizations should be as simple as printing out a dataframe. 
-When you print out the dataframe in the notebook, you should see the default Pandas table display with an additional Toggle button. 
+To visualize your dataframe in Lux, simply print out the dataframe. You should see the default Pandas table display with an additional toggle button.
 
 .. code-block:: python
 
@@ -37,7 +36,7 @@ When you print out the dataframe in the notebook, you should see the default Pan
   :align: center
   :alt: click on toggle, scroll on Correlation
 
-By clicking on the Toggle button, you can now explore the data visually through Lux. You should see three tabs of visualizations recommended to you. 
+By clicking on the Toggle button, you can now explore the data visually through Lux. You should see several categories of visualizations recommended to you by browsing through the different tabs. 
 
 .. image:: ../../../../lux-resources/doc_img/overview-2.gif
   :width: 700
@@ -75,7 +74,7 @@ As shown in the example above, by default, we display three types of actions sho
   :alt: Example of even and uneven category distributions
 
 
-Refer to :doc:`this page <../advanced/action>` for details on different types of action in Lux.
+Refer to :doc:`this page <../reference/lux.action>` for details on different types of action in Lux.
 
 Expressing Analysis Interest and Goals with User `Intent`
 ----------------------------------------------------------
@@ -111,7 +110,7 @@ You can specify a variety of things that you might be interested in, for example
     df.intent = ["MedianEarnings", "FundingModel=Public"]
     df
 
-For more advance use of intent, refer to :doc:`this page <../getting_started/intent>` on how to specify the intent.
+For more advance use of intent, refer to :doc:`this page <../guide/intent>` on how to specify the intent.
 
 Steering Recommendations via User Intent
 ----------------------------------------
@@ -129,7 +128,7 @@ Given the updated intent, additional actions (Enhance and Filter) are generated.
     - {MedianEarnings, **AverageCost**}
     - {MedianEarnings, **AverageFacultySalary**}.
 
-.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/overview-4.png
+.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/overview-4.png?raw=true
   :width: 700
   :align: center
   :alt: screenshot of Enhance
@@ -140,10 +139,7 @@ Given the updated intent, additional actions (Enhance and Filter) are generated.
     - {MedianEarnings, **Region=Southeast**}
     - {MedianEarnings, **Region=Great Lakes**}.
 
-.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/overview-5.png
+.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/overview-5.png?raw=true
   :width: 700
   :align: center
   :alt: screenshot of Filter
-
-
-.. Lux is built on the principle that users should always be able to visualize and explore anything they specify, without having to think about how the visualization should look like. 

doc/source/guide/FAQ.rst

@@ -12,38 +12,38 @@ Note that you must perform :code:`import lux` before you load in or create the d
 
 What if my data is stored in a relational database?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
-  Lux has `some limited support <https://lux-api.readthedocs.io/en/latest/source/advanced/executor.html#sql-executor>`_ for SQL (currently only tested for Postgres). We are actively working on extending Lux to databases. If you are interested in using this feature, please `contact us <http://lux-project.slack.com/>`_ for more information.
+  Lux has `some limited support <https://lux-api.readthedocs.io/en/latest/source/advanced/executor.html#sql-executor>`__ for SQL (currently only tested for Postgres). We are actively working on extending Lux to databases. If you are interested in using this feature, please `contact us <http://lux-project.slack.com/>`_ for more information.
 
 What do I do with date-related attributes in my dataset?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
-  Lux supports a variety of temporal data types in Pandas. For more information on how to handle temporal data in Lux, refer to `the datetime guide <https://lux-api.readthedocs.io/en/latest/source/advanced/date.html>`_.
+  Lux supports a variety of temporal data types in Pandas. For more information on how to handle temporal data in Lux, refer to `the datetime guide <https://lux-api.readthedocs.io/en/latest/source/advanced/date.html>`__.
 
 How do I access all of the current recommendations shown in my widget?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-  The recommendations for Lux can be accessed via the :code:`recommendation` property of the dataframe (e.g., df.recommendation).
+  The recommendations for Lux can be accessed via the :code:`recommendation` property of the dataframe (e.g., :code:`df.recommendation`).
 
 How do I set the Lux widgets to show up on default? 
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
-  By default, we show the Pandas display and users can use the toggle button to switch to the Lux display. The `default_display` property allows users to change the setting so that the Lux widget is set as the default view for future operations on the specified dataframe: 
+  By default, we show the Pandas display and users can use the toggle button to switch to the Lux display. The :code:`default_display` property allows users to change the setting so that the Lux widget is set as the default view for future operations: 
 
     .. code-block:: python
 
-        df.config.default_display = "lux"
+        lux.config.default_display = "lux"
 
   To switch back to Pandas as the default display: 
 
     .. code-block:: python
 
-        df.config.default_display = "pandas"
+        lux.config.default_display = "pandas"
 
 I want to change the opacity of my chart, add title, change chart font size, etc. How do I modify chart settings?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-  To add custom plot settings to the recommendations, you can set the global :code:`plot_config` property. See `this tutorial <https://lux-api.readthedocs.io/en/latest/source/guide/style.html>`_ on how to configure chart properties. Lux currently only support chart modifications in Altair.
+  To add custom plot settings to the recommendations, you can set the :code:`lux.config.plot_config` property. See `this tutorial <https://lux-api.readthedocs.io/en/latest/source/guide/style.html>`__ on how to configure chart properties. Lux currently only support chart modifications in Altair.
 
 How do I change aggregation functions, binning, or axis channels to non-default values?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
   To change the aggregation function to be something that is not average or set an attribute to display on the x-axis instead of y-axis, you can override the default values in the :code:`lux.Clause` specification.
-  To override automatically inferred properties, you can specify additional arguements inside `lux.Clause` to set the value of the Clause properties. See `this page <https://lux-api.readthedocs.io/en/latest/source/guide/intent.html#adding-constraints>`_ for more details.
+  To override automatically inferred properties, you can specify additional arguements inside :py:class:`lux.vis.Clause` to set the value of the Clause properties. See `this page <https://lux-api.readthedocs.io/en/latest/source/guide/intent.html#adding-constraints>`__ for more details.
 
 I want to look at the default recommendations that were recommended to me, how can I get the dataframe to display those?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -66,7 +66,7 @@ How do I turn off Lux?
 
 How do I disable sampling and have Lux visualize the full dataset?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-  Lux displays a warning saying "Large dataframe detected: Lux is only visualizing a random sample". If you would like to disable sampling, you can run: 
+  When visualizing large datasets, Lux may display a warning stating "`Large dataframe detected: Lux is only visualizing a random sample`". If you would like to disable sampling, you can run: 
 
   .. code-block:: python
 
@@ -79,12 +79,12 @@ How do I disable sampling and have Lux visualize the full dataset?
       lux.config.sampling = False
       df = pd.read_csv("...")
 
-  If you want to fine-tune the sampling parameters, you can edit :code:`lux.config.sampling_start` and :code:`lux.config.sampling_cap`. See `this page <https://lux-api.readthedocs.io/en/latest/source/reference/config.html>`_ for more details.
+  If you want to fine-tune the sampling parameters, you can edit :code:`lux.config.sampling_start` and :code:`lux.config.sampling_cap`. See `this page <https://lux-api.readthedocs.io/en/latest/source/reference/config.html>`__ for more details.
 
 Troubleshooting Tips
 --------------------
 
-To troubleshoot your Lux installation, we recommend cloning `this repo <https://github.com/lux-org/lux-binder>`_ and using one of the `demo notebooks <https://github.com/lux-org/lux-binder/blob/master/demo/cars_demo.ipynb>`_ to test out Lux.
+To troubleshoot your Lux installation, we recommend cloning `this repo <https://github.com/lux-org/lux-binder>`__ and using one of the `demo notebooks <https://github.com/lux-org/lux-binder/blob/master/demo/cars_demo.ipynb>`__ to test out Lux.
 
 The Lux Jupyter widget does not show up when I print a dataframe.
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -96,9 +96,10 @@ The Lux Jupyter widget does not show up when I print a dataframe.
         - Validating: OK
 
   - If you are able to import lux successfully and you do not see the "Toggle button" when you print the dataframe, it may be possible that Lux is not compatible with your browser. Lux is compatible with Google Chrome, but have not been extensively tested on Safari or Firefox.
-  - If you recieve the error message :code:`A Jupyter widget could not be displayed because the widget state could not be found.` This could happen if the kernel storing the widget is no longer available, or if the widget state was not saved in the notebook. You may be able to create the widget by running the appropriate cells.`, you may want to restart the notebook and rerun the cell.
+  - If you recieve the error message :code:`A Jupyter widget could not be displayed because the widget state could not be found.` This could happen if the kernel storing the widget is no longer available, or if the widget state was not saved in the notebook. You may be able to create the widget by running the particular cell again. If this doesn't work, then you may want try restarting the notebook and rerun the cell.
   - If you receive the error message :code:`ModuleNotFoundError: No module named 'luxwidget'`, it is possible that your luxwidget and lux-api versions are not in sync. The latest version of lux-api requires luxwidget v0.1 or above. Try running the following code:
   - If you receive the error message :code:`PermissionError: [Errno 13] Permission denied.` during the execution of the command :code:`jupyter nbextension install --py luxwidget`, then you can add the flag :code:`--user` (:code:`jupyter nbextension enable --py --user luxwidget`).
+  - Alternatively, if none of the above works. You can try creating a fresh virtual environment and follow the `quick install instructions <https://github.com/lux-org/lux#installation>`_.
 
   .. code-block:: bash
 
@@ -112,8 +113,6 @@ The Lux Jupyter widget does not show up when I print a dataframe.
 
     jupyter nbextension install --py luxwidget
     jupyter nbextension enable --py luxwidget
-
-  Alternatively, you can also try creating a fresh virtual environment and follow the `quick install instructions <https://github.com/lux-org/lux#installation>`_.
 
 
 I'm not able to export my visualizations via the :code:`exported` property.
@@ -140,7 +139,7 @@ I'm not able to export my visualizations via the :code:`exported` property.
 
 I have an issue that is not addressed by any of the FAQs.
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
-Please submit a `Github Issue <https://github.com/lux-org/lux/issues>`_ or ask a question on `Slack <http://lux-project.slack.com/>`_.
+Please submit a `Github Issue <https://github.com/lux-org/lux/issues>`__ or ask a question on `Slack <http://lux-project.slack.com/>`__.
 
 .. Not Currently Supported
 .. - What do I do if I want to change the data type of an attribute?

doc/source/guide/intent.rst

@@ -107,8 +107,9 @@ Note that since there are three different visualizations that is generated based
       :alt: add screenshot
 
     You can specify to Lux that you are interested in learning more about colleges in New England. 
-    In the resulting Filter action, we see that Lux suggests visualizations in other `Region`s as recommendations.
-
+
+    In the resulting Filter action, we see that Lux suggests visualizations in other `Region` as recommendations.
+
     .. code-block:: python
 
         df.intent = ["Region=New England"]

doc/source/guide/style.rst

@@ -115,4 +115,6 @@ We want to decrease the opacity of scatterplots, but keep the opacity for the ot
   :width: 700
   :align: center 
 
+.. note:: For now, if the visualization has already been rendered before, you will need to run `df.expire_recs()` to see the updated visualization.
+
 We can modify the scatterplot setting, without changing the settings for the other chart types.

doc/source/reference/API.rst

@@ -4,17 +4,35 @@
 API
 ****
 
+Core Lux Objects
+-----------------
+
+.. autosummary::
+	:toctree: gen
+	:nosignatures:
+
+	lux.core.frame.LuxDataFrame
+	lux.core.series.LuxSeries
+
+Configuration Options
+----------------------
+
+.. autosummary::
+	:toctree: gen
+	:nosignatures:
+
+	lux._config.config.Config
+
 Basic API Interface
 -------------------
 
 .. autosummary::
 	:toctree: gen
 	:nosignatures: 
-	
+
 	lux.vis.Vis.Vis
 	lux.vis.VisList.VisList
 	lux.vis.Vis.Clause
-	lux.core.frame.LuxDataFrame
 
 Advanced Internals (Dev)
 -------------------------