whole lotta docs tweaks

docs/_templates/page.html

@@ -0,0 +1,5 @@
+{% extends "!page.html" %}
+{% block menu %}
+{{ super() }}
+<iframe src="https://ghbtns.com/github-btn.html?user=mahmoud&repo=glom&type=star&count=true&size=medium" frameborder="0" scrolling="0" width="160px" height="30px" style="margin-left: 23px; margin-top: 10px;"></iframe>
+{% endblock %}

docs/api.rst

@@ -6,6 +6,8 @@
 .. contents:: Contents
    :local:
 
+.. _glom-func:
+
 The ``glom`` Function
 ---------------------
 
@@ -39,6 +41,9 @@ reporting, glom has a few more tricks up its sleeve.
 Conditional access and defaults with Coalesce
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Data isn't always where or what you want it to be. Use these
+specifiers to declare away overly branchy procedural code.
+
 .. autoclass:: glom.Coalesce
 
 .. autodata:: glom.OMIT
@@ -47,6 +52,9 @@ Conditional access and defaults with Coalesce
 Reducing lambda usage with Call
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+There's nothing quite like inserting a quick lambda into a glom spec
+to get the job done. But once a spec works, how can it be cleaned up?
+
 .. autofunction:: glom.Call
 
 Object-oriented access and method calls with ``T``
@@ -56,6 +64,7 @@ glom's shortest-named feature may be its most powerful.
 
 .. autodata:: glom.T
 
+.. _exceptions:
 
 Exceptions
 ----------
@@ -75,6 +84,8 @@ other standard Python exceptions as appropriate.
 
 .. autoclass:: glom.GlomError
 
+.. _debugging:
+
 Debugging
 ---------
 

docs/index.rst

@@ -1,43 +1,55 @@
 glom
 ====
 
-*Restructuring data through declarative object access and templating*
+*Restructuring data, the Python way*
 
 |release| |calver|
 
-**glom** is a new approach to working with data in Python.
+**glom** is a new approach to working with data in Python featuring:
 
-.. |release| image:: https://img.shields.io/pypi/v/glom.svg
-             :target: https://pypi.org/project/glom/
-
-.. |calver| image:: https://img.shields.io/badge/calver-YY.MINOR.MICRO-22bfda.svg
-            :target: https://calver.org
+* :ref:`Path-based access <access-granted>` for nested structures
+* :ref:`Declarative data transformation <glom-func>` using lightweight, Pythonic specifications
+* Readable, meaningful :ref:`error messages <exceptions>`
+* Built-in :ref:`data exploration and debugging <debugging>` features
+* And *more*!
 
+While it may sound like a lot, glom's straightforward approach becomes
+second-nature very quickly. :doc:`Get started with the five-minute
+tutorial! <tutorial>`
 
-.. toctree::
-   :maxdepth: 2
-
-   tutorial
-   api
-   cli
-   faq
-
-Installation and Integration
-----------------------------
+Installation
+------------
 
 glom is pure Python, and tested on Python 2.7-3.7, as well as
 PyPy. Installation is easy::
 
   pip install glom
 
-Then you're ready to get glomming!::
+Then you're ready to get glomming!
+
+.. code-block:: python
 
-  from  glom import glom
+   from glom import glom
 
-  target = {'a': {'b': {'c': 'd'}}}
-  glom(target, 'a.b.c')  # returns 'd'
+   target = {'a': {'b': {'c': 'd'}}}
+   glom(target, 'a.b.c')  # returns 'd'
 
-There's much, much more to glom, check out the tutorial and API reference!
+There's much, much more to glom, check out the :doc:`tutorial` and :doc:`API reference<api>`!
 
 
 *Just glom it! ☄️*
+
+
+.. |release| image:: https://img.shields.io/pypi/v/glom.svg
+             :target: https://pypi.org/project/glom/
+
+.. |calver| image:: https://img.shields.io/badge/calver-YY.MINOR.MICRO-22bfda.svg
+            :target: https://calver.org
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial
+   api
+   cli
+   faq

docs/tutorial.rst

@@ -1,10 +1,10 @@
 ``glom`` Tutorial
 =================
 
-Learn to use glom in 10 minutes or less!
+*Learn to use glom in 10 minutes or less!*
 
-Basic use of glom takes even less time, and wouldn't require a
-tutorial The case study below takes a wider look at day-to-day data
+Basic use of glom requires only a glance, not a whole tutorial. The
+case study below takes a wider look at day-to-day data and object
 manipulation, helping you develop an eye for writing robust,
 declarative data transformations.
 

glom/core.py

@@ -845,29 +845,41 @@ def _get_path(self, target, path):
         return val
 
     def glom(self, target, spec, **kwargs):
-        """Fetch or construct a new value from a given *target* based on the
+        """Access or construct a value from a given *target* based on the
         specification declared by *spec*.
 
-        ``glom`` also takes a keyword-argument, *default*. When set, a
-        ``glom`` operation fails with a :exc:`GlomError`, the
-        *default* will be returned, like :meth:`dict.get()`. The
-        *skip_exc* keyword argument controls which errors should be
-        ignored.
-
-        Fetch, aka deep-get:
+        Accessing nested data, aka deep-get:
 
         >>> target = {'a': {'b': 'c'}}
         >>> glom(target, 'a.b')
         'c'
 
-        Construct, aka restructure, aka conglomerate:
+        Here the *spec* was just a string denoting a path,
+        ``'a.b.``. As simple as it should be. The next example shows
+        how to use nested data to access many fields at once, and make
+        a new nested structure.
+
+        Constructing, or restructuring more-complicated nested data:
 
         >>> target = {'a': {'b': 'c', 'd': 'e'}, 'f': 'g', 'h': [0, 1, 2]}
-        >>> output = glom(target, {'a': 'a.b', 'd': 'a.d', 'h': ('h', [lambda x: x * 2])})
+        >>> spec = {'a': 'a.b', 'd': 'a.d', 'h': ('h', [lambda x: x * 2])}
+        >>> output = glom(target, spec)
         >>> pprint(output)
         {'a': 'c', 'd': 'e', 'h': [0, 2, 4]}
 
-        Glom's power is only surpassed by its intuitiveness. Give it a whirl!
+        ``glom`` also takes a keyword-argument, *default*. When set,
+        if a ``glom`` operation fails with a :exc:`GlomError`, the
+        *default* will be returned, very much like
+        :meth:`dict.get()`:
+
+        >>> glom(target, 'a.xx', default='nada')
+        'nada'
+
+        The *skip_exc* keyword argument controls which errors should
+        be ignored.
+
+        >>> glom({}, lambda x: 100.0 / len(x), default=0.0, skip_exc=ZeroDivisionError)
+        0.0
 
         Args:
            target (object): the object on which the glom will operate.
@@ -876,12 +888,14 @@ def glom(self, target, spec, **kwargs):
              any composition of these.
            default (object): An optional default to return in the case
              an exception, specified by *skip_exc*, is raised.
-
            skip_exc (Exception): An optional exception or tuple of
              exceptions to ignore and return *default* (None if
              omitted). If *skip_exc* and *default* are both not set,
              glom raises errors through.
 
+        It's a small API with big functionality, and glom's power is
+        only surpassed by its intuitiveness. Give it a whirl!
+
         """
         # TODO: check spec up front
         default = kwargs.pop('default', None if 'skip_exc' in kwargs else _MISSING)

glom/tutorial.py

@@ -2,8 +2,9 @@
 
 .. note::
 
-   glom's tutorial is a runnable module, feel free to run ``from
-   glom.tutorial import *`` in the Python REPL and glom along.
+   glom's tutorial is a runnable module, feel free to run ``pip
+   install glom`` and ``from glom.tutorial import *`` in the Python
+   REPL to glom along.
 
 Dealing with Data
 =================
@@ -32,9 +33,15 @@
 we wouldn't know if ``'a'``, ``'b'``, or ``'c'`` had been set to
 ``None``.
 
-What we need is a more semantically powerful accessor.
+If only there were a more semantically powerful accessor.
 
-Maybe something like::
+.. _access-granted:
+
+Access Granted
+==============
+
+After years of research and countless iterations, the glom team landed
+on this simple construct::
 
   >>> glom(data, 'a.b.c')
   'd'