Add docs and maup.doctor() utiltity! (#33)

* Add doctor utils

* Add docs!

* Add more asserts to the maup.doctor() function

* Fix isinstance error in maup.doctor()

* Add more information to the package description, etc.

README.md

@@ -14,7 +14,7 @@ districts, such as
 -   [Disaggregating data from precincts down to blocks](#disaggregating-data-from-precincts-down-to-blocks),
 -   [Prorating data when units do not nest neatly](#prorating-data-when-units-do-not-nest-neatly),
     and
--   [Fixing overlaps and gaps](#fixing-topological-issues-overlaps-and-gaps)
+-   [Fixing topological issues, overlaps, and gaps](#fixing-topological-issues-overlaps-and-gaps)
 
 The project's priorities are to be efficient by using spatial indices whenever
 possible and to integrate well with the existing ecosystem around

best-practices.md

@@ -0,0 +1,31 @@
+# MAUP Best Practice Guidelines
+Last updated on June 16th, 2021 by Max Fan (@InnovativeInventor).
+
+*Note: Some features are only available in `maup`'s `1.0` release.*
+
+## Introduction
+Prorating votes from one set of geometries to another is a tricky business. 
+The [MAUP problem](https://en.wikipedia.org/wiki/Modifiable_areal_unit_problem) is inherently difficult to address, as any solution requires relying on various statistical assumptions. 
+
+Even the most common invocation of `maup` (prorating vote data by population), entails several assumptions:
+
+- Perfect tiling of source and target geometries without holes or overlaps
+- For any given region, population is greater than or equal to the number of votes cast
+- Uniformly proportional voter turnout (this is practically unavoidable)
+
+Other invocations of `maup` may include more assumptions. For example, assigning block-level data to precincts by greatest shared area also entails the added assumption that 
+
+If not properly understood and managed, these assumptions could introduce serious biases in the final data product.
+
+## Best Practices Checklist
+- [ ] Ensure that source and target geometries are perfectly tiled and well-formed by using the `maup.doctor(source, target)` tool, which will return `True` if the source and/or target is well-formed.
+- [ ] Resolve tiling, overlap, and gap issues manually or by using `maup.resolve_overlaps()`, `maup.close_gaps()`, and `maup.autofix()` as needed with low relative_threshold tolerances.
+- [ ] Ensure that you are prorating by population, not area.
+- [ ] Ensure your weights are normalized by calling `maup.normalize(weights, level=0)`.
+- [ ] If you are aggregating/disaggregating data, use a blessed method of invoking `maup`, as shown in the [README](https://github.com/mggg/maup#readme). Other methods are not guaranteed to work and should be used with deliberate care.
+
+## Filing Bug Reports and Support
+Contributions and bug reports are welcome! 
+If `maup.doctor()` returns `True` and you encounter an issue (you get an error or votes go missing), then it is vital that you file a bug report! 
+If you encounter other issues, bug reports are also welcome!
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/maup.adjacencies.rst

@@ -0,0 +1,7 @@
+maup.adjacencies module
+=======================
+
+.. automodule:: maup.adjacencies
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.assign.rst

@@ -0,0 +1,7 @@
+maup.assign module
+==================
+
+.. automodule:: maup.assign
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.crs.rst

@@ -0,0 +1,7 @@
+maup.crs module
+===============
+
+.. automodule:: maup.crs
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.indexed_geometries.rst

@@ -0,0 +1,7 @@
+maup.indexed\_geometries module
+===============================
+
+.. automodule:: maup.indexed_geometries
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.indices.rst

@@ -0,0 +1,7 @@
+maup.indices module
+===================
+
+.. automodule:: maup.indices
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.intersections.rst

@@ -0,0 +1,7 @@
+maup.intersections module
+=========================
+
+.. automodule:: maup.intersections
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.normalize.rst

@@ -0,0 +1,7 @@
+maup.normalize module
+=====================
+
+.. automodule:: maup.normalize
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.progress_bar.rst

@@ -0,0 +1,7 @@
+maup.progress\_bar module
+=========================
+
+.. automodule:: maup.progress_bar
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.repair.rst

@@ -0,0 +1,7 @@
+maup.repair module
+==================
+
+.. automodule:: maup.repair
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/maup.rst

@@ -0,0 +1,26 @@
+maup package
+============
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   maup.adjacencies
+   maup.assign
+   maup.crs
+   maup.indexed_geometries
+   maup.indices
+   maup.intersections
+   maup.normalize
+   maup.progress_bar
+   maup.repair
+
+Module contents
+---------------
+
+.. automodule:: maup
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/modules.rst

@@ -0,0 +1,7 @@
+maup
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   maup

docs/conf.py

@@ -0,0 +1,78 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'maup'
+copyright = '2021, MGGG'
+author = 'Max Hully, Max Fan'
+
+# The full version, including alpha/beta/rc tags
+release = '0.6.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser', 
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'numpydoc',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+]
+
+# apidoc
+apidoc_module_dir = '../maup'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = ['tests']
+apidoc_separate_modules = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "github_url": "https://github.com/numpy/numpydoc",
+    "show_prev_next": False,
+    "navbar_end": ["search-field.html", "navbar-icon-links.html"],
+}
+html_sidebars = {
+    "**": [],
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,51 @@
+.. maup documentation master file, created by
+   sphinx-quickstart on Wed Jun 16 16:05:45 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to maup's API documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+``maup`` is the geospatial toolkit for redistricting data. The package streamlines
+the basic workflows that arise when working with blocks, precincts, and
+districts, such as
+
+-   Assigning precincts to districts
+-   Aggregating block data to precincts
+-   Disaggregating data from precincts down to blocks
+-   Prorating data when units do not nest neatly
+-   Fixing topological issues, overlaps, and gaps
+
+Quick help:
+
+- `Example usage <https://github.com/mggg/maup#readme>`_
+- `Best practice guidelines <https://github.com/mggg/maup/blob/main/best-practices.md>`_ 
+- `API reference </reference/api/maup.html>`_ 
+
+
+Installation
+------------
+
+Install ``maup`` by running::
+
+    pip install maup
+
+
+Contribute
+----------
+
+All contributions are welcome! `maup` is licensed under the MIT license.
+
+- Issue Tracker: https://github.com/mggg/maup/issues
+- Source Code: https://github.com/mggg/maup
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/reference/api/maup.adjacencies.rst

@@ -0,0 +1,7 @@
+maup.adjacencies module
+=======================
+
+.. automodule:: maup.adjacencies
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.assign.rst

@@ -0,0 +1,7 @@
+maup.assign module
+==================
+
+.. automodule:: maup.assign
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.crs.rst

@@ -0,0 +1,7 @@
+maup.crs module
+===============
+
+.. automodule:: maup.crs
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.indexed_geometries.rst

@@ -0,0 +1,7 @@
+maup.indexed\_geometries module
+===============================
+
+.. automodule:: maup.indexed_geometries
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.indices.rst

@@ -0,0 +1,7 @@
+maup.indices module
+===================
+
+.. automodule:: maup.indices
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.intersections.rst

@@ -0,0 +1,7 @@
+maup.intersections module
+=========================
+
+.. automodule:: maup.intersections
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.normalize.rst

@@ -0,0 +1,7 @@
+maup.normalize module
+=====================
+
+.. automodule:: maup.normalize
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/api/maup.progress_bar.rst

@@ -0,0 +1,7 @@
+maup.progress\_bar module
+=========================
+
+.. automodule:: maup.progress_bar
+   :members:
+   :undoc-members:
+   :show-inheritance: