Update and simplify README

.github/workflows/docbuild.yml

@@ -22,6 +22,7 @@ jobs:
         pip install "selenium<4.3.0"
         pip install altair_saver
         pip install -r doc/requirements.txt
+        pip uninstall vl-convert-python --yes
         pip install git+https://github.com/altair-viz/altair_viewer.git
     - name: Run docbuild
       run: |

CONTRIBUTING.md

@@ -11,23 +11,18 @@ visualization.
 We are also seeking contributions of additional Jupyter notebook-based examples
 in our separate GitHub repository: https://github.com/altair-viz/altair_notebooks.
 
-The altair users mailing list can be found at
-https://groups.google.com/forum/#!forum/altair-viz. If you are working on
-Altair, you can talk to other developers in the `#altair` channel of the [Vega
-slack](https://bit.ly/join-vega-slack).
-
 ## How To Contribute Code to Altair
 
 ### Setting Up Your Environment
 
-Fork the Altair repository on GitHub and clone the fork to you local
+Fork the Altair repository on GitHub and then clone the fork to you local
 machine. For more details on forking see the [GitHub
 Documentation](https://help.github.com/en/articles/fork-a-repo).
 ```
 $ git clone https://github.com/YOUR-USERNAME/altair.git
 ```
 
-To keep your fork up to date with changes in the this repo,
+To keep your fork up to date with changes in this repo,
 you can [use the fetch upstream button on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
 
 Now you can install the latest version of Altair locally using `pip`.
@@ -36,14 +31,11 @@ every time you open a new Python interpreter
 (instead of having to reinstall the package each time).
 ```
 $ cd altair/ 
-$ python -m pip install -e .
-```
-
-You can now install the development requirements using
-```
-$ python -m pip install -r requirements_dev.txt
+$ python -m pip install -e '.[dev]'
 ```
 
+'[dev]' indicates that pip should also install the development requirements
+which you can find in `requirements_dev.txt`
 
 ### Creating a Branch
 
@@ -55,14 +47,6 @@ $ git switch -c <branch-name>
 ```
 With this branch checked-out, make the desired changes to the package.
 
-Note that Altair code uses the [black](https://black.readthedocs.io/)
-code formatter and [flake8](https://flake8.pycqa.org/en/latest/) linter
-which you can apply to your modifications by running:
-```
-$ black --diff .  # View changes
-$ black .  # Apply changes
-$ flake8 .  --statistics  # View changes (fix manually)
-```
 
 ### Testing your Changes
 
@@ -74,6 +58,9 @@ which includes a number of tests to validate the correctness of your code:
 $ make test
 ```
 
+This also runs the [black](https://black.readthedocs.io/)
+code formatter and [flake8](https://flake8.pycqa.org/en/latest/) linter.
+
 Study the output of any failed tests and try to fix the issues
 before proceeding to the next section.
 
@@ -98,7 +85,18 @@ automatically shown in the PR.
 Hopefully your PR will be answered in a timely manner and your contribution will
 help others in the future.
 
-## Adding Examples
+## Documentation
+Altair documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html)
+and compiled into html pages using [Sphinx](http://www.sphinx-doc.org/en/master/).
+Contributing to the documentation requires some extra dependencies and 
+we have some conventions and plugins that are used to help navigate the docs and 
+generate great Altair visualizations. 
+
+Note that the [Altair website](https://altair-viz.github.io/)
+is only updated when a new version is released so your contribution might not show
+up for a while.
+
+### Adding Examples
 
 We are always interested in new examples contributed from the community.  These
 could be everything from simple one-panel scatter and line plots, to more
@@ -154,7 +152,36 @@ Some additional notes:
   included then it should be referenced by URL, such as `source =
   data.movies.url`. This is to ensure that Altair's automated test suite does
   not depend on availability of external HTTP resources.
-
-Note that examples shown on the [Altair website](https://altair-viz.github.io/)
-are only updated when a new version is released so your new example might not show
-up there for a while. 
+
+### Building the Documentation Locally
+In addition to the development dependencies mentioned further above,
+you will also need to install the dependencies for the documentation 
+listed in  `docs/requirements.txt`. Note that `geopandas` might require you to first
+install some other dependencies, see [their installation page](https://geopandas.org/en/stable/getting_started/install.html#installation)
+for details.
+
+```
+pip install -r doc/requirements.txt
+```
+
+If you want to build the documentation so it can be published on the [official Altair website](https://altair-viz.github.io), you need to
+additionally install [altair_saver](https://github.com/altair-viz/altair_saver/) and uninstall [vl-convert-python](https://github.com/vega/vl-convert/tree/main/vl-convert-python).
+These packages are used to generate PNG thumbnails for the example gallery. If both are installed, `vl-convert-python` is used by default.
+The reason for this is that `vl-convert-python` cannot create a thumbnail for the `isotype_emoji.py` example,
+which is fine for normal contributions but not when creating a new version of the official documentation.
+
+Once you have all the dependencies, you can build the documentation 
+using various commands defined in the Makefile. 
+From the `doc` folder, you can use `make help` to see all of the available commands
+which control the type of documentation you want to generate.
+
+Usually, you will want to run `make html` which will generate the documentation
+in a sub folder `_build/html`. You can then view the documentation by running:
+
+```
+cd _build/html
+python -m http.server
+```
+
+and then opening `http://localhost:8000` in your browser.
+

README.md

@@ -7,10 +7,6 @@
 [![code style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![JOSS Paper](https://joss.theoj.org/papers/10.21105/joss.01057/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01057)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/altair)](https://pypi.org/project/altair)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/altair-viz/altair_notebooks/master?urlpath=lab/tree/notebooks/Index.ipynb)
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)
-
-[https://altair-viz.github.io](https://altair-viz.github.io)
 
 **Vega-Altair** is a declarative statistical visualization library for Python. With Vega-Altair, you can spend more time understanding your data and its meaning. Vega-Altair's
 API is simple, friendly and consistent and built on top of the powerful
@@ -19,10 +15,13 @@ simplicity produces beautiful and effective visualizations with a minimal amount
 Granger](https://github.com/ellisonbg) in close collaboration with the [UW
 Interactive Data Lab](https://idl.cs.washington.edu/).*
 
-## Vega-Altair Documentation
+## Documentation
+
+See [Vega-Altair's Documentation Site](https://altair-viz.github.io) as well as the [Tutorial Notebooks](https://github.com/altair-viz/altair_notebooks). You can
+run the notebooks directly in your browser by clicking on one of the following badges:
 
-See [Vega-Altair's Documentation Site](https://altair-viz.github.io),
-as well as Vega-Altair's [Tutorial Notebooks](https://github.com/altair-viz/altair_notebooks).
+[![Binder](https://beta.mybinder.org/badge.svg)](https://beta.mybinder.org/v2/gh/altair-viz/altair_notebooks/master)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)
 
 ## Example
 
@@ -76,160 +75,48 @@ points & bars
 
 ![Vega-Altair Visualization Gif](https://raw.githubusercontent.com/altair-viz/altair/master/images/cars_scatter_bar.gif)
 
-
-## Getting your Questions Answered
-
-If you have a question that is not addressed in the documentation, there are several ways to ask:
-
-- open a [Github Issue](https://github.com/altair-viz/altair/issues)
-- post a [StackOverflow Question](https://stackoverflow.com/questions/tagged/altair) (be sure to use the `altair` tag)
-- ask on the [Vega-Altair Google Group](https://groups.google.com/forum/#!forum/altair-viz)
-
-We'll do our best to get your question answered
-
-## A Python API for statistical visualizations
-
-Vega-Altair provides a Python API for building statistical visualizations in a declarative
-manner. By statistical visualization we mean:
-
-* The **data source** is a `DataFrame` that consists of columns of different data types (quantitative, ordinal, nominal and date/time).
-* The `DataFrame` is in a [tidy format](https://vita.had.co.nz/papers/tidy-data.pdf)
-  where the rows correspond to samples and the columns correspond to the observed variables.
-* The data is mapped to the **visual properties** (position, color, size, shape,
-  faceting, etc.) using the group-by data transformation.
-
-The Vega-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. The resulting
-Vega-Lite JSON data can be rendered in the following user-interfaces:
-
-* [Jupyter Notebook](https://github.com/jupyter/notebook) (by installing [ipyvega](https://github.com/vega/ipyvega)).
-* [JupyterLab](https://github.com/jupyterlab/jupyterlab) (no additional dependencies needed).
-* [nteract](https://github.com/nteract/nteract) (no additional dependencies needed).
-
 ## Features
-
-* Carefully-designed, declarative Python API based on
-  [traitlets](https://github.com/ipython/traitlets).
+* Carefully-designed, declarative Python API.
 * Auto-generated internal Python API that guarantees visualizations are type-checked and
   in full conformance with the [Vega-Lite](https://github.com/vega/vega-lite)
   specification.
-* Display visualizations in the live Jupyter Notebook, JupyterLab, nteract, on GitHub and
-  [nbviewer](https://nbviewer.jupyter.org/).
-* Export visualizations to PNG/SVG images, stand-alone HTML pages and the
+* Display visualizations in JupyterLab, Jupyter Notebook, Visual Studio Code, on GitHub and
+  [nbviewer](https://nbviewer.jupyter.org/), and many more.
+* Export visualizations to various formats such as PNG/SVG images, stand-alone HTML pages and the
 [Online Vega-Lite Editor](https://vega.github.io/editor/#/).
 * Serialize visualizations as JSON files.
-* Explore Vega-Altair with dozens of examples in the [Example Gallery](https://altair-viz.github.io/gallery/index.html)
 
 ## Installation
+Vega-Altair can be installed with:
+```bash
+pip install altair
+```
 
-To use Vega-Altair for visualization, you need to install two sets of tools
-
-1. The core Vega-Altair Package and its dependencies
-
-2. The renderer for the frontend you wish to use (i.e. `Jupyter Notebook`,
-   `JupyterLab`, or `nteract`)
-
-Vega-Altair can be installed with either ``pip`` or with ``conda``.
-For full installation instructions, please see
-https://altair-viz.github.io/getting_started/installation.html
-
-## Example and tutorial notebooks
-
-We maintain a separate Github repository of Jupyter Notebooks that contain an
-interactive tutorial and examples:
-
-https://github.com/altair-viz/altair_notebooks
-
-To launch a live notebook server with those notebook using [binder](https://mybinder.org/) or
-[Colab](https://colab.research.google.com), click on one of the following badges:
-
-[![Binder](https://beta.mybinder.org/badge.svg)](https://beta.mybinder.org/v2/gh/altair-viz/altair_notebooks/master)
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)
-
-## Project philosophy
-
-Many excellent plotting libraries exist in Python, including the main ones:
-
-* [Matplotlib](https://matplotlib.org/)
-* [Bokeh](https://bokeh.pydata.org/en/latest/)
-* [Seaborn](https://seaborn.pydata.org/)
-* [Lightning](https://github.com/lightning-viz/lightning)
-* [Plotly](https://plot.ly/)
-* [Pandas built-in plotting](https://pandas.pydata.org/pandas-docs/stable/visualization.html)
-* [HoloViews](https://holoviews.org)
-* [VisPy](https://vispy.org/)
-* [pygg](https://www.github.com/sirrice/pygg)
-
-Each library does a particular set of things well.
-
-### User challenges
-
-However, such a proliferation of options creates great difficulty for users
-as they have to wade through all of these APIs to find which of them is the
-best for the task at hand. None of these libraries are optimized for
-high-level statistical visualization, so users have to assemble their own
-using a mishmash of APIs. For individuals just learning data science, this
-forces them to focus on learning APIs rather than exploring their data.
-
-Another challenge is current plotting APIs require the user to write code,
-even for incidental details of a visualization. This results in an unfortunate
-and unnecessary cognitive burden as the visualization type (histogram,
-scatterplot, etc.) can often be inferred using basic information such as the
-columns of interest and the data types of those columns.
-
-For example, if you are interested in the visualization of two numerical
-columns, a scatterplot is almost certainly a good starting point. If you add
-a categorical column to that, you probably want to encode that column using
-colors or facets. If inferring the visualization proves difficult at times, a
-simple user interface can construct a visualization without any coding.
-[Tableau](https://www.tableau.com/) and the [Interactive Data
-Lab's](https://idl.cs.washington.edu/)
-[Polestar](https://github.com/vega/polestar) and
-[Voyager](https://github.com/vega/voyager) are excellent examples of such UIs.
-
-### Design approach and solution
-
-We believe that these challenges can be addressed without the creation of yet
-another visualization library that has a programmatic API and built-in
-rendering. Vega-Altair's approach to building visualizations uses a layered design
-that leverages the full capabilities of existing visualization libraries:
-
-1. Create a constrained, simple Python API (Vega-Altair) that is purely declarative
-2. Use the API (Vega-Altair) to emit JSON output that follows the Vega-Lite spec
-3. Render that spec using existing visualization libraries
-
-This approach enables users to perform exploratory visualizations with a much
-simpler API initially, pick an appropriate renderer for their usage case, and
-then leverage the full capabilities of that renderer for more advanced plot
-customization.
-
-We realize that a declarative API will necessarily be limited compared to the
-full programmatic APIs of Matplotlib, Bokeh, etc. That is a deliberate design
-choice we feel is needed to simplify the user experience of exploratory
-visualization.
+If you are using the conda package manager, the equivalent is:
+```bash
+conda install altair -c conda-forge
+```
 
-## Development install
+For full installation instructions, please see [the documentation](https://altair-viz.github.io/getting_started/installation.html).
 
-Instructions on how to install Vega-Altair for development can be found in
-[the documentation](https://altair-viz.github.io/getting_started/installation.html).
+## Getting Help
+If you have a question that is not addressed in the documentation, 
+you can post it on [StackOverflow](https://stackoverflow.com/questions/tagged/altair) using the `altair` tag
+or ask on the [Vega-Altair Google Group](https://groups.google.com/forum/#!forum/altair-viz).
+For bugs and feature requests, please open a [Github Issue](https://github.com/altair-viz/altair/issues).
 
-## Testing
+## Development
+You can find the instructions on how to install the package for development in [the documentation](https://altair-viz.github.io/getting_started/installation.html).
 
-To run the test suite you must have [py.test](https://pytest.org/latest/) installed.
 To run the tests, use
-
 ```
-py.test --pyargs altair
+pytest --doctest-modules altair
 ```
-(you can omit the `--pyargs` flag if you are running the tests from a source checkout).
-
-## Feedback and Contribution
 
-See [`CONTRIBUTING.md`](https://github.com/altair-viz/altair/blob/master/CONTRIBUTING.md)
+For information on how to contribute your developments back to the Vega-Altair repository, see
+[`CONTRIBUTING.md`](https://github.com/altair-viz/altair/blob/master/CONTRIBUTING.md)
 
 ## Citing Vega-Altair
-
 [![JOSS Paper](https://joss.theoj.org/papers/10.21105/joss.01057/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01057)
 
 If you use Vega-Altair in academic work, please consider citing https://joss.theoj.org/papers/10.21105/joss.01057 as
@@ -248,7 +135,7 @@ If you use Vega-Altair in academic work, please consider citing https://joss.the
     journal = {Journal of Open Source Software}
 }
 ```
-Please additionally consider citing the [vega-lite](https://vega.github.io/vega-lite/) project, which Vega-Altair is based on: https://dl.acm.org/doi/10.1109/TVCG.2016.2599030
+Please additionally consider citing the [Vega-Lite](https://vega.github.io/vega-lite/) project, which Vega-Altair is based on: https://dl.acm.org/doi/10.1109/TVCG.2016.2599030
 ```bib
 @article{Satyanarayan2017,
     author={Satyanarayan, Arvind and Moritz, Dominik and Wongsuphasawat, Kanit and Heer, Jeffrey},
@@ -261,7 +148,3 @@ Please additionally consider citing the [vega-lite](https://vega.github.io/vega-
     publisher={IEEE}
 } 
 ```
-
-## Whence Vega-Altair?
-
-The Vega project was named after the brightest star in the constellation Lyra; nearby 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).