change explanation of "posit" in notebook

authorityspoke/rules.py

@@ -219,10 +219,20 @@ def contradiction_between_outputs(
         return False
 
     def contradicts(self, other) -> None:
+        """
+        Raises an error because, by analogy with :meth:`Procedure.implies`\,
+        users might expect this method to return ``True`` only when
+        :class:`ProceduralRule` with ``universal=False`` and Procedure ``self``
+        would contradict another :class:`ProceduralRule` with ``universal=False``
+        and Procedure ``other``. But that would never happen.
+
+        :returns: None
+        """
+
         raise NotImplementedError(
             "Procedures do not contradict one another unless one of them ",
-            "applies in 'ALL' cases. Consider using the ",
-            "'contradicts_some_to_all' method.",
+            "applies in 'ALL' cases. Consider using ",
+            "'Procedure.contradicts_some_to_all' or 'ProceduralRule.contradicts'.",
         )
 
     def contradicts_some_to_all(self, other: Procedure) -> bool:
@@ -689,24 +699,44 @@ def list_from_records(
 
     @property
     def context_factors(self) -> Tuple:
+        """
+        :returns:
+            context_factors from ``self``'s :class:`Procedure`
+        """
         return self.procedure.context_factors
 
     @property
     def despite(self):
+        """
+        :returns:
+            despite :class:`.Factors` from ``self``'s :class:`Procedure`
+        """
         return self.procedure.despite
 
     @property
     def generic_factors(self) -> List[Optional[Factor]]:
+        """
+        :returns:
+            generic :class:`.Factors` from ``self``'s :class:`Procedure`
+        """
         if self.generic:
             return [self]
         return self.procedure.generic_factors
 
     @property
     def inputs(self):
+        """
+        :returns:
+            input :class:`.Factors` from ``self``'s :class:`Procedure`
+        """
         return self.procedure.inputs
 
     @property
     def outputs(self):
+        """
+        :returns:
+            output :class:`.Factors` from ``self``'s :class:`Procedure`
+        """
         return self.procedure.outputs
 
     def contradicts(self, other) -> bool:

docs/index.rst

@@ -7,6 +7,11 @@
 AuthoritySpoke: Reading Legal Authority for the Last Time
 =========================================================
 
+Release v\. |release|.
+
+See the `GitHub repo <https://github.com/mscarey/AuthoritySpoke>`_
+for examples and to try out AuthoritySpoke in a Jupyter Notebook.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

notebooks/introduction.ipynb

@@ -243,11 +243,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can link some legal analysis to each opinion by using its `exposit` method. The parameter we pass to this function is the name of a JSON file containing structured information about the legal holdings posited by the opinion. Sadly, the `exposit` method requires you to exposit the Opinion for the computer's benefit, not the other way around.\n",
+    "Now we can link some legal analysis to each opinion by using its `exposit` method. The parameter we pass to this function is the name of a JSON file containing structured information about the legal holdings posited by the opinion. Sadly, the `exposit` method requires a user to exposit the Opinion for the computer's benefit, not the other way around.\n",
     "\n",
-    "A terminology note: When an Opinion asserts that a Rule is valid law, the Opinion **posits** the Rule and makes the Rule one of the Opinion's **holdings**. When you, as a reader, assert that an Opinion posited a Rule, you **exposit** the Opinion.\n",
+    "A terminology note: When an Opinion asserts that a Rule is valid law, the Opinion **posit**s the Rule and makes the Rule one of the Opinion's **holdings**. When you use AuthoritySpoke to link a complete set of Rules for an Opinion, you **exposit** the Opinion. The `Opinion.exposit()` method is the equivalent of loading a set of Rules from a JSON file and then calling `Opinion.posit()` on each of those Rules.\n",
     "\n",
-    "Anyway, the example JSON files have already been created and AuthoritySpoke should find them when we call the `exposit` method."
+    "The example JSON files that you'll need to continue with this demonstration have already been created and AuthoritySpoke should find them when we call the `exposit` method."
    ]
   },
   {