update links in docstrings

authorityspoke/context.py

@@ -13,8 +13,9 @@ def log_mentioned_context(func: Callable):
 
     If factor_record is a :class:`str` instead of a :class:`dict`, looks up the
     corresponding factor in "mentioned" and returns that instead of
-    constructing a new Factor. Also, if a newly-constructed Factor
-    has a name attribute, logs the factor in "mentioned" for later use.
+    constructing a new :class:`Factor`. Also, if the newly-constructed
+    :class:`Factor` has a ``name`` attribute, logs the :class:`Factor`
+    in ``mentioned`` for later use.
     """
 
     @functools.wraps(func)
@@ -57,8 +58,9 @@ def wrapper(
 
 def get_directory_path(stem: str) -> pathlib.Path:
     """
-    This function finds a data directory for importing files, if cwd
-    is that directory, is its parent directory, or is a sibling
+    This function finds a data directory for importing files, if
+    the current working directory is that directory, is its
+    parent directory, or is a sibling
     directory. Otherwise it won't find the right directory.
 
     This function doesn't obviously belong in the context module.

authorityspoke/enactments.py

@@ -119,7 +119,7 @@ class Enactment:
     :class:`.ProceduralRule`. To retrieve the text, there needs
     to be an available method for identifying the correct XML
     element based on the section and subsection names, and each
-    XML format used for a :class:`Code` requires a different method.
+    XML format used for any :class:`Code` will require a different method.
 
     :param code:
         the :class:`Code` where this legislative text appears.
@@ -143,7 +143,7 @@ class Enactment:
     :param name:
         an identifier for this object, often used if the object needs
         to be referred to multiple times in the process of composing
-        other :class:`Factor` objects.
+        other :class:`.Factor` objects.
     """
 
     code: Code
@@ -220,7 +220,11 @@ def usc_statute_text():
     @log_mentioned_context
     def from_dict(cls, enactment_dict: Dict[str, str]) -> Enactment:
         """
-        No way to use an existing :class:`Code` object currently.
+        Creates a new :class:`Enactment` object using a :class:`dict`
+        imported from JSON example data.
+
+        There's currently no way to import an existing :class:`Code` object
+        for use in composing the new :class:`Enactment`.
         """
         code = Code(enactment_dict["code"])
         start = enactment_dict.get("start")
@@ -242,10 +246,15 @@ def from_dict(cls, enactment_dict: Dict[str, str]) -> Enactment:
 
     def means(self, other: Enactment) -> bool:
         """
-        It's questionable whether this comparison is really meaningful.
-        You could always make the result ``False`` by comparing longer
-        passages of text until you found a difference between the two
-        sites in the text.
+        Whether the meaning of ``self`` is equivalent to (neither
+        broader nor narrower than) the meaning of the legislative
+        text passage ``other``.
+
+        .. note::
+            You could always make the result ``False`` by comparing longer
+            passages of text until you found a difference between the two
+            sites in the text. Does this undercut the usefulness of the
+            ``means`` method?
 
         :returns:
             whether ``self`` and ``other`` represent the same text
@@ -266,8 +275,10 @@ def __str__(self):
 
     def __ge__(self, other):
         """
-        Why does this method not require the same ``code.sovereign`` and
-        ``code.level``, especially considering that :meth:`means` does?
+        .. note::
+            Why does this method not require the same ``code.sovereign``
+            and ``code.level``, especially considering that
+            :meth:`means` does?
 
         :returns:
             Whether ``self`` "implies" ``other``, which in this context means

authorityspoke/entities.py

@@ -1,10 +1,3 @@
-"""
-Entity and its subclasses are subclasses of Factor that represent
-people, places, or things. Unlike Facts, Evidence, and Allegations
-(which are also subclasses of Factor), Entities don't take Predicates
-as parameters, so they won't (probably?) need to incorporate
-ordered tuples of other Factors.
-"""
 from __future__ import annotations
 
 from typing import Dict, Iterator, Optional
@@ -18,12 +11,12 @@
 class Entity(Factor):
     """
     A person, place, thing, or event that needs to be mentioned in
-    multiple :class:`Factor`\s in a :class:`Rule`, often in the
-    :class:`Predicate` of a :class:`Fact` object.
+    multiple :class:`.Factor`\s in a :class:`.Rule`, often in the
+    :class:`.Predicate` of a :class:`.Fact` object.
 
     An :class:`Entity` is often, but not always, ``generic`` with
-    respect to the meaning of the :class:`Rule` in which it is
-    mentioned, which means that the :class:`Rule` is understood
+    respect to the meaning of the :class:`.Rule` in which it is
+    mentioned, which means that the :class:`.Rule` is understood
     to apply generally even if some other :class:`Entity` was
     substituted.
 
@@ -37,7 +30,7 @@ class Entity(Factor):
     :param generic:
         Determines whether a change in the ``name`` of the
         :class:`Entity` would change the meaning of the
-        :class:`Factor` in which the :class:`Entity` is
+        :class:`.Factor` in which the :class:`Entity` is
         embedded.
 
     :param plural:
@@ -52,9 +45,9 @@ class Entity(Factor):
 
     def means(self, other):
         """
-        ``generic`` :class:`Entity` objects are considered equal
-        as long as they're the same class. If not ``generic``, they're
-        considered equal if all their attributes are the same.
+        ``generic`` :class:`Entity` objects are considered equivalent
+        in meaning as long as they're the same class. If not ``generic``,
+        they're considered equivalent if all their attributes are the same.
         """
 
         if self.__class__ != other.__class__:
@@ -104,22 +97,24 @@ def new_context(self, context: Dict[Factor, Factor]) -> Entity:
 
 class Association(Entity):
     """
-    An entity representing a set of people such as members or shareholders,
+    An :class:`Entity` representing a set of people such as members or shareholders,
     or a business such as a corporation or LLC, but not an unincorporated
     business such as a sole proprietorship.
     """
 
 class Human(Entity):
     """
-    A "natural person" mentioned as an entity in a factor. On the distinction
-    between "human" and "person", see Slaughter-House Cases, 83 U.S. 36, 99.
-    https://www.courtlistener.com/opinion/88661/slaughter-house-cases/
+    A "natural person" mentioned as an :class:`Entity` in a factor. On the distinction
+    between "human" and "person", see `Slaughter-House Cases
+    <https://www.courtlistener.com/opinion/88661/slaughter-house-cases/>`_
+    , 83 U.S. 36, 99.
     """
 
 
 class Event(Entity):
     """
-    Events may be referenced as entities in a predicate's content.
-    See Lepore, Ernest. Meaning and Argument: An Introduction to Logic
-    Through Language. Section 17.2: The Event Approach
+    An Event may be referenced as an :class:`Entity` in a
+    :class:`Predicate`\'s ``content``.
+    *See* Lepore, Ernest. Meaning and Argument: An Introduction to Logic
+    Through Language. Section 17.2: The Event Approach.
     """

authorityspoke/factors.py

@@ -69,9 +69,9 @@ class Factor(ABC):
     """
     Anything relevant to a court's determination of the applicability
     of a legal :class:`.Rule` can be a :class:`Factor`. The same
-    :class:`Factor` that is in the :attr:`.Procedure.outputs`
-    for one legal :class:`.Rule` might be in the :attr:`.Procedure.inputs`
-    for another.
+    :class:`Factor` that is in the outputs for the :class:`.Procedure`
+    of one legal :class:`.Rule` might be in the ``inputs`` of the
+    :class:`.Procedure` for another.
     """
 
     @classmethod
@@ -171,9 +171,9 @@ def interchangeable_factors(self) -> List[Dict[Factor, Factor]]:
     def generic_factors(self) -> List[Optional[Factor]]:
         """
         :returns:
-            a :class:`dict` with self's generic :class:`Factor`\s
+            a :class:`dict` with self's generic :class:`.Factor`\s
             as keys and ``None`` as values, so that the keys can
-            be matched to  another object's ``generic_factors``
+            be matched to another object's ``generic_factors``
             to perform an equality test.
         """
 
@@ -446,11 +446,11 @@ def make_generic(self) -> Factor:
     def new_context(self, changes: Dict[Factor, Factor]) -> Factor:
         """
         :param changes:
-            has :class:`Factor`\s to replace as keys, and has
+            has :class:`.Factor`\s to replace as keys, and has
             their replacements as the corresponding values.
 
         :returns:
-            a new :class:`Factor` object with the replacements made.
+            a new :class:`.Factor` object with the replacements made.
         """
         new_dict = self.__dict__.copy()
         for name in self.context_factor_names:
@@ -618,7 +618,7 @@ class Fact(Factor):
 
     :param case_factors:
         a series of :class:`Factor`\s that have already been mentioned
-        in the :class:`Opinion`. They are available for composing the
+        in the :class:`.Opinion`. They are available for composing the
         new :class:`Factor` object and don't need to be recreated.
     """
 
@@ -954,13 +954,14 @@ def __str__(self):
 
 @dataclass(frozen=True)
 class Exhibit(Factor):
-    """A source of information for use in litigation.
+    """
+    A source of information for use in litigation.
 
     "derived_from" and and "offered_by" parameters were removed
-    because the former is probably better represented as a Fact,
-    and the latter as a Motion.
+    because the former is probably better represented as a :class:`Fact`,
+    and the latter as a :class:`Motion`.
 
-    Allowed inputs for "form" will need to be limited.
+    TODO: Allowed inputs for ``form`` will need to be limited.
     """
 
     form: Optional[str] = None
@@ -994,8 +995,10 @@ def __str__(self):
 
 @dataclass(frozen=True)
 class Evidence(Factor):
-    """An Exhibit that has been admitted by the court to aid a
-    factual determination."""
+    """
+    An :class:`Exhibit` that has been admitted by the court to aid a
+    factual determination.
+    """
 
     exhibit: Optional[Exhibit] = None
     to_effect: Optional[Fact] = None

authorityspoke/predicates.py

@@ -45,11 +45,11 @@ class Predicate:
         are intended to apply to quantities above or below some threshold.
 
     :param quantity:
-        a Python number object or :class:`ureg.Quantity`
-        from the `pint <pint.readthedocs.io>`_ library. Comparisons to
+        a Python number object or :class:`ureg.Quantity` from the
+        `pint <https://pint.readthedocs.io/en/0.9/>`_ library. Comparisons to
         quantities can be used to determine whether :class:`Predicate`\s
-        imply or contradict each other. A single Predicate may contain
-        no more than one ``comparison`` and one ``quantity``.
+        imply or contradict each other. A single :class:`Predicate`
+        may contain no more than one ``comparison`` and one ``quantity``.
     """
 
     content: str
@@ -96,7 +96,7 @@ def __post_init__(self):
     def context_slots(self) -> int:
         """
         :returns:
-            the number of context :class:`Factor`\s that must be
+            the number of context :class:`.Factor`\s that must be
             specified to fill in the blanks in ``self.content``.
         """
 
@@ -108,8 +108,8 @@ def context_slots(self) -> int:
     def content_with_entities(self, context: Union[Factor, Sequence[Factor]]) -> str:
         """
         :param context:
-            generic :class:`Factor`\s to be mentioned in the context of
-            this Predicate. Does not need to be type :class:`Entity`.
+            generic :class:`.Factor`\s to be mentioned in the context of
+            this Predicate. Does not need to be type :class:`.Entity`.
 
         :returns:
             a sentence created by substituting string representations
@@ -204,16 +204,16 @@ def from_string(
         """
         This method for constructing :class:`Predicate` objects
         from strings may never be used because it's an alternative to
-        :meth:`Fact.from_dict`. This function identifies context
+        :meth:`.Factor.from_dict`. This function identifies context
         factors by finding brackets around them, while
-        :meth:`Fact.from_dict` depends on knowing the names of the
+        :meth:`~.Factor.from_dict` depends on knowing the names of the
         context factors in advance.
 
         :param content:
             a string containing a clause making an assertion.
             Differs from the ``content`` parameter in
             the :meth:`__init__` method because the curly brackets
-            surround the names of :class:`Entity` context factors,
+            surround the names of :class:`.Entity` context factors,
             and because the ``comparison`` and ``quantity`` are
             represented in the ``content`` string rather than as
             separate parameters.
@@ -229,7 +229,7 @@ def from_string(
             any entities interchangeable other than the first two.
 
         :returns:
-            a :class:`Predicate` and :class:`Entity` objects
+            a :class:`Predicate` and :class:`.Entity` objects
             from a string that has curly brackets around the
             context factors and the comparison/quantity.
         """
@@ -262,7 +262,7 @@ def __gt__(self, other: Optional[Predicate]) -> bool:
         :returns:
             whether ``self`` implies ``other``, which is ``True``
             if their statements about quantity imply it.
-            Returns ``False`` if ``self`` and ``other`` are equal.
+            Returns ``False`` if ``self == other``.
         """
 
         if other is None:

authorityspoke/relations.py

@@ -15,8 +15,8 @@ class Relation:
     the relation.
 
     :param need_matches:
-        :class:`.Factor`\s that all need to satisfy the comparison
-        :attr:`comparison` with some factor of :attr:`available`
+        :class:`.Factor`\s that all need to satisfy the ``comparison``
+        with some :class:`.Factor` of ``available``
         for the relation to hold.
 
     :param available: