beartype.claw docos x 2.

This commit is the next in a commit chain documenting the
`beartype.claw` subpackage first introduced with @beartype 0.15.0 at our
official ReadTheDocs (RTD)-hosted site. Specifically, this commit
revises various introductory sections outlining the gist of this
subpackage drafted by the prior commit.
(*Lollipop-lolling cyclops on a triceratops *or* expedient encyclopedia?*)

doc/src/api_claw.rst

@@ -25,27 +25,29 @@ cubicle.
 
 .. code-block:: python
 
-   # In your "{your_package}.__init__" submodule in a codebase far, far away...
-   from beartype.claw import beartype_this_package  # <-- boilerplate for victory
-   beartype_this_package()                          # <-- yay! your team just won
+   # Add *ONE* of the following semantically equivalent two-liners to the very
+   # top of your "{your_package}.__init__" submodule. Start with the fast way.
 
-**That's it.** That's beartype import hooks in ten seconds.
-:superscript:`dyslexia notwithstanding` As the simplest of several import hooks
-published by the :mod:`beartype.claw` subpackage, the
-:func:`.beartype_this_package` function:
+   # ....................{ THE FAST WAY                    }....................
+   from beartype.claw import beartype_this_package  # <-- this is boring
+   beartype_this_package()                          # <-- the fast way
 
-* Implicitly decorates *all* callables and classes in ``{your_package}`` by the
-  :func:`beartype.beartype` decorator. Rejoice, fellow mammals! You no longer
-  need to explicitly decorate anything by :func:`beartype.beartype` ever again.
-  Of course, you *can* if you want to – but there's no compelling reason to do
-  so and many compelling reasons *not* to do so. You have probably just thought
-  of five, but there are even more.
-* Implicitly subjects *all* :pep:`526`\ -compliant annotated variable
-  assignments (e.g., ``muh_int: int = 'Pretty sure this isn't an integer, but
-  not sure.'``) to runtime type-checking performed by the
-  :func:`beartype.door.die_if_unbearable` function. More below.
+   # ....................{ THE LESS FAST WAY               }....................
+   from beartype.claw import beartype_package       # <-- still boring
+   beartype_package('{your_package}')               # <-- the less fast way
+
+   # ....................{ THE MORE SLOW WAY               }....................
+   from beartype.claw import beartype_packages      # <-- boring intensifies
+   beartype_packages(('{your_package}',))           # <-- the more slow way
 
-The :mod:`beartype.claw` rabbit hole goes deep. Prepare to enter that hole.
+   # ....................{ THE WAY OF THE BEAR NINJA       }....................
+   from beartype.claw import beartyping             # <-- getting weird here
+   with beartyping():                               # <-- weird context manager
+       from {your_package} import {your_thing}      # <-- import some stuff
+       from {some_package} import {some_thing}      # <-- import more stuff
+
+**That's it.** That's beartype import hooks in ten seconds.
+:superscript:`dyslexia notwithstanding`
 
 .. # ------------------( TABLES OF CONTENTS                  )------------------
 .. # Table of contents, excluding the above document heading. While the
@@ -78,6 +80,75 @@ Claw your way to the top of the bug heap threatening to drown your codebase in a
 deluge of chittering carapaces, masticating mandibles, and probing probosci. The
 bugginess you feel may be real, but so is the bug-mugging power of beartype.
 
+Import Hooks Overview, Part Deux
+################################
+
+Beartype import hooks is a hobbit hole that goes deeper than any Baggins ever
+envisioned. Prepare to enter that hole.
+
+Let's begin by outlining exactly what :func:`.beartype_this_package` does. As
+the simplest and most convenient of several import hooks published by the
+:mod:`beartype.claw` subpackage, the :func:`.beartype_this_package` import hook
+subjects *all* subsequently imported submodules of ``{your_package}`` to
+runtime type-checking based on purportedly high-tech :mod:`beartype` tech.
+
+Notably, :func:`.beartype_this_package`:
+
+* Implicitly decorates *all* callables and classes by the
+  :func:`beartype.beartype` decorator. Rejoice, fellow mammals! You no longer
+  need to explicitly decorate anything by :func:`beartype.beartype` ever again.
+  Of course, you *can* if you want to – but there's no compelling reason to do
+  so and many compelling reasons *not* to do so. You have probably just thought
+  of five, but there are even more.
+* Implicitly appends *every* :pep:`526`\ -compliant annotated variable
+  assignment (e.g., ``muh_int: int = 'Pretty sure this isn't an integer, but
+  not sure.'``) by a new statement at the same indentation level calling the
+  :func:`beartype.door.die_if_unbearable` function passed both that variable and
+  that type hint.
+
+For example, :func:`.beartype_this_package` silently transforms your
+``{your_package}.buggy_submodule`` submodule that lacks runtime type-checking
+from this broken code you pretend you never about:
+
+.. code-block:: python
+
+   import typing as t
+
+   bad_global: int = 'My eyes! The goggles do nothing.'
+
+   def bad_function() -> str:
+       return b"I could've been somebody, instead of a bum byte string."
+
+   class BadClass(object):
+       def bad_method(self) -> t.NoReturn:
+           return 'Nobody puts BadClass in the corner.'
+
+...into this broken code you can no longer ignore:
+
+.. code-block:: python
+
+   from beartype import beartype
+   from beartype.door import die_if_unbearable
+   import typing as t
+
+   bad_global: int = 'My eyes! The goggles do nothing.'
+   die_if_unbearable(bad_global, int)
+
+   @beartype
+   def bad_function() -> str:
+       return b"I could've been somebody, instead of a bum byte string."
+
+   @beartype
+   class BadClass(object):
+       def bad_method(self) -> t.NoReturn:
+           return 'Nobody puts BadClass in the corner.'
+
+By doing nothing, you saved five lines of extraneous boilerplate you no longer
+need to maintain, preserved `DRY (Don't Repeat Yourself) <DRY_>`__, and saved
+your coworker's career. You had nothing to do with that code!
+
+This is why we :func:`.beartype_this_package`.
+
 Import Hooks API
 ################
 
@@ -100,8 +171,8 @@ Idempotent Import Hooks
 ***********************
 
 .. # FIXME: Revise signature up, please.
-.. py:function::
-   beartyping( \
-       *, \
-       conf: beartype.BeartypeConf = beartype.BeartypeConf(), \
-   ) -> None
+.. # .. py:function::
+.. #    beartyping( \
+.. #        *, \
+.. #        conf: beartype.BeartypeConf = beartype.BeartypeConf(), \
+.. #    ) -> None

doc/src/index.rst

@@ -73,8 +73,9 @@ If seeing is believing, prepare to do both those things.
 
 .. code-block:: python
 
-   from beartype.claw import beartype_this_package       # <-- hype comes
-   beartype_this_package()                               # <-- hype goes
+   # At the very top of your "{your_package}.__init__" submodule:
+   from beartype.claw import beartype_this_package  # <-- boilerplate for victory
+   beartype_this_package()                          # <-- yay! your team just won
 
 Beartype now implicitly type-checks *all* annotated classes, callables, and
 variable assignments across *all* submodules of ``{your_package}``. Congrats.