Documentation updates in preparation for initial release (#29)

* Documentation updates

* Update README.md

README.md

@@ -39,8 +39,11 @@ https://faceted.readthedocs.io/en/latest/.
 Installation
 ------------
 
-Currently, the only way to install `faceted` is directly from the source.  You
-can do so using `pip`:
+You can install `faceted` either from PyPI:
+```
+$ pip install faceted
+```
+or directly from source:
 ```
 $ git clone https://github.com/spencerkclark/faceted.git
 $ cd faceted

doc/conf.py

@@ -62,8 +62,8 @@
     'IPython.sphinxext.ipython_console_highlighting',
 ]
 
-extlinks = {'issue': ('https://github.com/pydata/faceted/issues/%s', 'GH'),
-            'pull': ('https://github.com/pydata/faceted/pull/%s', 'PR')}
+extlinks = {'issue': ('https://github.com/spencerkclark/faceted/issues/%s', 'GH'),
+            'pull': ('https://github.com/spencerkclark/faceted/pull/%s', 'PR')}
 
 autosummary_generate = True
 

doc/index.rst

@@ -35,7 +35,11 @@ use.
 Installation
 ------------
 
-Currently the only option for installing ``faceted`` is from source::
+You can install :py:mod:`faceted` from PyPI::
+
+  $ pip install faceted
+
+or directly from source::
 
   $ git clone https://github.com/spencerkclark/faceted.git
   $ cd faceted

doc/why-faceted.rst

@@ -236,7 +236,7 @@ the colorbar size parameters:
 
 .. ipython:: python
 
-    a = 75. / 360.
+    a = 75. / 360
     p_cbar = 0.25
     h_panel = a * w_panel
     h = p_bottom + p_top + h_panel + p_cbar + w_cbar
@@ -272,25 +272,33 @@ the colorbar size parameters:
 As examples go, this one was actually fairly simple; we only had one row of
 panels, rather than multiple, and we only had one colorbar.  Taking the
 :py:meth:`matplotlib.pyplot.subplots` approach was remarkably complicated.
-Admittedly, it would be 
-*slightly* more straightforward to use the :py:class:`mpl_toolkits.axes_grid1.AxesGrid` framework to do this,
-but other problems remain with that approach; e.g. using :py:class:`mpl_toolkits.axes_grid1.AxesGrid` with
-cartopy is not ideal due to axes sharing issues (`SciTools/cartopy#939
-<https://github.com/SciTools/cartopy/issues/939>`_), and colorbars drawn using
-:py:class:`mpl_toolkits.axes_grid1.AxesGrid` are drawn using an outdated colorbar class in :py:mod:`matplotlib`,
-which is different than the one used by default (`matplotlib/matplotlib#9778
-<https://github.com/matplotlib/matplotlib/issues/9778>`_). In
-:py:meth:`faceted.faceted` we use :py:class:`mpl_toolkits.axes_grid1.AxesGrid` to aid in the placing the axes
-and colorbars (some math is still required to determine the figure height), but
-we do not use the axes generated by it.  Instead we create our own, 
-which are modern and have working axes-sharing capabilities.  In so doing we
-create a :py:meth:`matplotlib.pyplot.subplots`-like interface, which is
-slightly more intuitive to use than :py:class:`mpl_toolkits.axes_grid1.AxesGrid`.
+
+What about AxesGrid?
+--------------------
+
+In theory, it would be more straightforward to use the
+:py:class:`mpl_toolkits.axes_grid1.AxesGrid` framework to do this.  Having said 
+that, it would still require a bit of math to determine the appropriate figure
+height.  In addition there are some other problems with that approach, e.g.
+
+- Using :py:class:`mpl_toolkits.axes_grid1.AxesGrid` with 
+  cartopy is not ideal due to axes sharing issues (`SciTools/cartopy#939 <https://github.com/SciTools/cartopy/issues/939>`_).
+- Colorbars drawn using :py:class:`mpl_toolkits.axes_grid1.AxesGrid` are drawn
+  using an outdated colorbar class in :py:mod:`matplotlib`, which is different
+  than the one used by default (`matplotlib/matplotlib#9778 <https://github.com/matplotlib/matplotlib/issues/9778>`_).
+
+In :py:mod:`faceted` we use :py:class:`mpl_toolkits.axes_grid1.AxesGrid` to aid
+in the placing the axes and colorbars, but we do not use the axes generated by
+it.  Instead we create our own, which are modern and have working axes-sharing
+capabilities. In so doing we create a
+:py:meth:`matplotlib.pyplot.subplots`-like interface, which is slightly more
+intuitive to use than :py:class:`mpl_toolkits.axes_grid1.AxesGrid` with or
+without :py:mod:`cartopy`.
 
 How would you do this in faceted?
 ---------------------------------
 
-In :py:meth:`faceted.faceted` this becomes much simpler; there is no need to do any algebra
+In :py:mod:`faceted` this becomes much simpler; there is no need to do any algebra
 or post-hoc adjustment of the axes placement; everything gets handled in the
 top-level function.
 
@@ -322,14 +330,19 @@ top-level function.
 What can't you do in faceted?
 -----------------------------
 
-The main thing that :py:meth:`faceted.faceted` cannot do is create a
+The main thing that :py:mod:`faceted` cannot do is create a
 constrained set of axes 
 that have varying size, or varying properties. For more complex figure
 construction tasks we recommend using a more fundamental :py:mod:`matplotlib`
 approach, either using :py:class:`mpl_toolkits.axes_grid1.AxesGrid`,
 :py:class:`matplotlib.GridSpec`, or `Constrained Layout
 <https://matplotlib.org/tutorials/intermediate/constrainedlayout_guide.html#>`_. The
-main reason for creating :py:meth:`faceted.faceted` was that these other tools
+main reason for creating :py:mod:`faceted` was that these other tools
 were *too* flexible at the expense of simplicity.  For a large percentage of
 the use cases, they are not required, but for the remaining percentage they are
 indeed quite useful.
+
+Currently only figures constrained by width and panel aspect ratio are
+possible in :py:mod:`faceted`.  That said, figures constrained by any two of
+the width, height, and panel aspect ratio would be within scope.  See
+:issue:`15` for discussion.