[WIP] DOC: Updating tutorial

README.md

@@ -7,7 +7,18 @@
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
+`mapclassify` implements a family of classification schemes for choropleth maps.
+Its focus is on the determination of the number of classes, and the assignment
+of observations to those classes. It is intended for use with upstream mapping
+and geovisualization packages (see
+[geopandas](https://geopandas.org/mapping.html) and
+[geoplot](https://residentmario.github.io/geoplot/user_guide/Customizing_Plots.html))
+that handle the rendering of the maps.
+
+For further theoretical background see [Rey, S.J., D. Arribas-Bel, and L.J. Wolf (2020) "Geographic Data Science with PySAL and the PyData Stack”](https://geographicdata.science/book/notebooks/05_choropleth.html).
+
 ## Using `mapclassify`
+Load built-in example data reporting employment density in 58 California counties:
 
 ```python
 >>> import mapclassify
@@ -320,3 +331,17 @@ array([5, 1, 2, 3, 2, 1, 5, 1, 3, 3, 1, 2, 2, 1, 2, 2, 2, 1, 5, 2, 4, 1, 2,
 9  4  0  4
 
 ```
+
+
+## Development Notes
+
+Because we use `geopandas` in development, and geopandas has stable `mapclassify` as a dependency, setting up a local development installation involves creating a conda environment, then replacing the stable `mapclassify` with the development version of `mapclassify` in the development environment. This can be accomplished with the following steps:
+
+
+```
+conda-env create -f environment.yml
+conda activate mapclassify
+conda remove -n mapclassify mapclassify
+pip install -e .
+```
+

ci/36-numba.yaml

@@ -14,6 +14,7 @@ dependencies:
   - matplotlib
   # optional
   - geopandas
+  - palettable
   - zstd
   - networkx
   - libpysal

ci/36.yaml

@@ -13,6 +13,7 @@ dependencies:
   - codecov
   - matplotlib
   # optional
+  - palettable
   - geopandas
   - zstd
   - networkx

ci/37-numba.yaml

@@ -14,6 +14,7 @@ dependencies:
   - matplotlib
   # optional
   - geopandas
+  - palettable
   - zstd
   - networkx
   - libpysal

ci/37.yaml

@@ -14,6 +14,7 @@ dependencies:
   - matplotlib
   # optional
   - geopandas
+  - palettable
   - zstd
   - networkx
   - libpysal

ci/38-numba.yaml

@@ -14,6 +14,7 @@ dependencies:
   - matplotlib
   # optional
   - geopandas
+  - palettable
   - zstd
   - networkx
   - libpysal

ci/38.yaml

@@ -14,6 +14,7 @@ dependencies:
   - matplotlib
   # optional
   - geopandas
+  - palettable
   - zstd
   - networkx
   - libpysal

docsrc/Makefile

@@ -19,6 +19,10 @@ help:
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+notebooks:
+	rm notebooks/*
+	cp ../notebooks/??_*.ipynb notebooks/.
+
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf auto_examples/

docsrc/conf.py

@@ -43,7 +43,8 @@
               'sphinx.ext.doctest',
               'sphinx.ext.intersphinx',
               'numpydoc',
-              'matplotlib.sphinxext.plot_directive']
+              'matplotlib.sphinxext.plot_directive',
+              'nbsphinx']
 
 
 # Add any paths that contain templates here, relative to this directory.
@@ -60,7 +61,7 @@
 
 # General information about the project.
 project = "mapclassify"  # string of your project name, for example, 'giddy'
-copyright = '2018, pysal developers'
+copyright = '2018-, pysal developers'
 author = 'pysal developers'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -168,6 +169,7 @@
     # Navigation bar menu
     'navbar_links': [
                      ("Installation", "installation"),
+                     ("Tutorial", "tutorial"),
                      ("API", "api"),
                      ("References", "references"),
                      ],

docsrc/index.rst

@@ -49,6 +49,7 @@ mapclassify is an open-source python library for Choropleth map classification.
    :caption: Contents:
 
    Installation <installation>
+   Tutorial <tutorial>
    API <api>
    References <references>
 

docsrc/installation.rst

@@ -3,13 +3,18 @@
 Installation
 ============
 
-mapclassify supports python `3.5`_ and `3.6`_ only. Please make sure that you are
+mapclassify supports python `3.6`_, `3.7`_, and `3.8`_. Please make sure that you are
 operating in a python 3 environment.
 
 Installing released version
 ---------------------------
 
-mapclassify is available on the `Python Package Index`_. Therefore, you can either
+mapclassify is available in on `conda`_ via the `conda-forge`_ channel::
+
+  conda install -c conda-forge mapclassify
+
+
+mapclassify is also available on the `Python Package Index`_. Therefore, you can either
 install directly with `pip` from the command line::
 
   pip install -U mapclassify
@@ -36,8 +41,11 @@ your fork. By making changes
 to your local clone and submitting a pull request to `pysal/mapclassify`_, you can
 contribute to mapclassify development.
 
-.. _3.5: https://docs.python.org/3.5/
 .. _3.6: https://docs.python.org/3.6/
+.. _3.7: https://docs.python.org/3.7/
+.. _3.8: https://docs.python.org/3.8/
+.. _conda: https://docs.conda.io/en/latest/
+.. _conda-forge: https://anaconda.org/conda-forge/mapclassify
 .. _Python Package Index: https://pypi.org/project/mapclassify/
 .. _pysal/mapclassify: https://github.com/pysal/mapclassify
 .. _fork: https://help.github.com/articles/fork-a-repo/