From 3459346ab7de661e3927ca12469245c55da2f72c Mon Sep 17 00:00:00 2001 From: Grant Nestor Date: Fri, 10 Mar 2017 16:12:07 -0800 Subject: [PATCH] Replace ipyvega with jupyterlab_vega in docs --- README.md | 24 +++++++++++++++--------- altair/api.py | 2 +- altair/utils/server.py | 2 +- doc/documentation/displaying.rst | 13 ++++++------- doc/installation.rst | 14 ++++++++------ setup.py | 2 +- 6 files changed, 32 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 6e9b9f1ca..fe1783aaa 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ as well as Altair's [Tutorial Notebooks](altair/notebooks/01-Index.ipynb). ## Example -Here is an example using Altair to quickly visualize and display a dataset with the native Vega-Lite renderer in the Jupyter Notebook: +Here is an example using Altair to quickly visualize and display a dataset with +the native Vega-Lite renderer in the Jupyter Notebook: ```python from altair import Chart, load_dataset @@ -51,8 +52,8 @@ manner. By statistical visualization we mean: The Altair API contains no actual visualization rendering code but instead emits JSON data structures following the [Vega-Lite](https://github.com/vega/vega-lite) specification. For convenience, -Altair can optionally use [ipyvega](https://github.com/vega/ipyvega) to -display client-side renderings seamlessly in the Jupyter notebook. +Altair can optionally use [jupyterlab_vega](https://github.com/altair-viz/jupyterlab_vega) to +display client-side renderings seamlessly in the Jupyter Notebook. ## Features @@ -168,10 +169,11 @@ Altair requires the following dependencies: * [traitlets](https://github.com/ipython/traitlets) * [IPython](https://github.com/ipython/ipython) -For visualization in the IPython/Jupyter notebook using the Vega-Lite renderer, Altair additionally requires +For visualization in the IPython/Jupyter Notebook using the Vega-Lite renderer, +Altair additionally requires * [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html) -* [ipyvega](https://github.com/vega/ipyvega) +* [jupyterlab_vega](https://github.com/altair-viz/jupyterlab_vega) If you have cloned the repository, run the following command from the root of the repository: @@ -193,6 +195,7 @@ To run the tests, use ``` py.test --pyargs altair ``` + (you can omit the `--pyargs` flag if you are running the tests from a source checkout). ## Feedback and Contribution @@ -205,10 +208,13 @@ as much bigger than Altair itself: the Vega and Vega-Lite specifications are perhaps the best existing candidates for a principled *lingua franca* of data visualization. -To contribute additional examples to the documentation please add or -update notebooks in `altair/notebooks/*.ipynb` and open a pull request. -Be sure to add links to `01-Index.ipynb` if needed. Thanks! +To contribute additional examples to the documentation please add or update +notebooks in `altair/notebooks/*.ipynb` and open a pull request. Be sure to add +links to `01-Index.ipynb` if needed. Thanks! ## Whence Altair? -Altair is the [brightest star](https://en.wikipedia.org/wiki/Altair) in the constellation Aquila, and along with Deneb and Vega forms the northern-hemisphere asterism known as the [Summer Triangle](https://en.wikipedia.org/wiki/Summer_Triangle). +Altair is the [brightest star](https://en.wikipedia.org/wiki/Altair) in the +constellation Aquila, and along with Deneb and Vega forms the +northern-hemisphere asterism known as the [Summer +Triangle](https://en.wikipedia.org/wiki/Summer_Triangle). diff --git a/altair/api.py b/altair/api.py index 1d00c89f9..8f530b94d 100644 --- a/altair/api.py +++ b/altair/api.py @@ -322,7 +322,7 @@ def serve(self, ip='127.0.0.1', port=8888, n_retries=50, files=None, dictionary of extra content to serve jupyter_warning : bool (optional) if True (default), then print a warning if this is used - within the Jupyter notebook + within the Jupyter Notebook open_browser : bool (optional) if True (default), then open a web browser to the given HTML http_server : class (optional) diff --git a/altair/utils/server.py b/altair/utils/server.py index ec6011c36..06a145f4c 100644 --- a/altair/utils/server.py +++ b/altair/utils/server.py @@ -13,7 +13,7 @@ from ._py3k_compat import server, IO JUPYTER_WARNING = """ -Note: if you're in the Jupyter notebook, Chart.serve() is not the best +Note: if you're in the Jupyter Notebook, Chart.serve() is not the best way to view plots. Consider using Chart.display(). You must interrupt the kernel to cancel this command. """ diff --git a/doc/documentation/displaying.rst b/doc/documentation/displaying.rst index 437a7b106..799b66ef2 100644 --- a/doc/documentation/displaying.rst +++ b/doc/documentation/displaying.rst @@ -51,9 +51,11 @@ Displaying Plots in Jupyter Notebook Perhaps the most straightforward way to interactively create and render Altair visualizations is in the `Jupyter Notebook`_. -If you have installed correctly configured the `ipyvega`_ package -(See :ref:`Installation`), then a chart on the last line of a code cell -will automatically be represented within the notebook as a rendered plot: + +`jupyterlab_vega`_ is an extension for both Jupyter Notebook and JupyterLab. +Once installed and enabled, it will render all Altair charts using vega-embed. +You can render a chart by returning it (calling it on the last line of a code +cell) or using ``.display()`` on a Altair ``Chart`` object. .. altair-plot:: @@ -66,9 +68,6 @@ will automatically be represented within the notebook as a rendered plot: color='Origin:N', ) -Alternatively, you can use ``chart.display()`` to more explicitly display -any chart object - .. _displaying-plots-html: Outputting Plots as HTML @@ -195,4 +194,4 @@ please send comments or contributions via Altair's .. _Vega-Lite Online Editor: https://vega.github.io/vega-editor/?mode=vega-lite .. _Vega-Lite: https://github.com/vega/vega-lite .. _Jupyter Notebook: https://jupyter.readthedocs.io/en/latest/install.html -.. _ipyvega: http://github.com/vega/ipyvega +.. _jupyterlab_vega: https://github.com/altair-viz/jupyterlab_vega diff --git a/doc/installation.rst b/doc/installation.rst index 59fea9f32..20c92515e 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -8,12 +8,14 @@ Altair can be installed via the Python Package Index with the following: $ pip install altair $ pip install --upgrade notebook - $ jupyter nbextension install --sys-prefix --py vega + $ pip install jupyterlab_vega + $ jupyter nbextension install --sys-prefix --py jupyterlab_vega + $ jupyter nbextension enable --sys-prefix --py jupyterlab_vega -The additional commands serve to set-up the `ipyvega`_ module to automatically -render Altair plots within the Jupyter notebook (see :ref:`displaying-plots-jupyter`) -Alternatively, you can install with conda_, which handles the Jupyter notebook -setup within the single install command: +The additional commands serve to set-up the `jupyterlab_vega`_ package to +automatically render Altair plots within the Jupyter Notebook (see +:ref:`displaying-plots-jupyter`) Alternatively, you can install with conda_, +which handles the Jupyter Notebook setup within the single install command: .. code-block:: bash @@ -33,7 +35,7 @@ Additionally, the following optional dependencies are required to use Altair within the Jupyter Notebook: - `Jupyter Notebook`_ -- ipyvega_ +- jupyterlab_vega_ Development Install ------------------- diff --git a/setup.py b/setup.py index 0e419a679..97550fc20 100644 --- a/setup.py +++ b/setup.py @@ -23,7 +23,7 @@ .. _Altair Github Repository: http://github.com/altair-viz/altair/ .. _Altair Documentation: http://altair-viz.github.io/ .. _Vega-Lite: https://github.com/vega/vega-lite -.. _ipyvega: https://github.com/vega/ipyvega +.. _jupyterlab_Vega: https://github.com/altair-viz/jupyterlab_vega """ DESCRIPTION = "Altair: A declarative statistical visualization library for Python."