reorganize API docs table of contents

authorityspoke/courts.py

@@ -15,6 +15,16 @@ class Court:
     An institution that issues :class:`.Opinion`\s and decides litigation.
 
     Has :class:`.Judge`\s and may be inferior to other :class:`Court`\s.
+
+    :param id:
+        an identifier
+
+    :param opinions:
+        a list of :class:`.Opinion`\s issued
+
+    :param inferior_to:
+        a :class:`Court` with the power to overrule
+        :class:`.Rule`\s posited by this :class:`Court`
     """
 
     id: str

authorityspoke/factors.py

@@ -17,7 +17,7 @@
 
 from authorityspoke.context import log_mentioned_context, new_context_helper
 from authorityspoke.predicates import Predicate
-from authorityspoke.relations import Relation
+from authorityspoke.relations import Analogy
 
 @dataclass(frozen=True)
 class Factor(ABC):
@@ -111,7 +111,7 @@ def context_factor_names(self) -> Tuple[str, ...]:
 
         :returns:
             attribute names identifying which attributes of ``self`` and
-            ``other`` must match, for a :class:`.Relation` to hold between
+            ``other`` must match, for a :class:`.Analogy` to hold between
             this :class:`Factor` and another.
         """
 
@@ -215,7 +215,7 @@ def _context_registers(
         elif self.generic or other.generic:
             yield {self: other, other: self}
         else:
-            relation = Relation(self.context_factors, other.context_factors, comparison)
+            relation = Analogy(self.context_factors, other.context_factors, comparison)
             for register in relation.ordered_comparison():
                 yield register
 
@@ -1062,8 +1062,8 @@ def means(left: Factor, right: Factor) -> bool:
     """
     Call :meth:`.Factor.means` as function alias.
 
-    This only exists because :class:`.Relation` objects expect
-    a function rather than a method for :attr:`~.Relation.comparison`.
+    This only exists because :class:`.Analogy` objects expect
+    a function rather than a method for :attr:`~.Analogy.comparison`.
 
     :returns:
         whether ``other`` is another :class:`Factor` with the same

authorityspoke/relations.py

@@ -9,12 +9,12 @@
 
 
 @dataclass(frozen=True)
-class Relation:
+class Analogy:
     """
     Two groups of :class:`.Factor`\s and a function that must hold between them.
 
     Can be used to find ways to assign the :class:`.Factor`\s'
-    context assignments consistently with the ``Relation``.
+    context assignments consistently with the ``Analogy``.
 
     :param need_matches:
         :class:`.Factor`\s that all need to satisfy the ``comparison``
@@ -138,15 +138,15 @@ def update_matchlist(
         self, matchlist: List[Dict[Factor, Factor]]
     ) -> List[Dict[Factor, Optional[Factor]]]:
         """
-        Filter :class:`list` of :class:`.Factor` assignments with :meth:`~Relation.unordered_comparison`.
+        Filter :class:`list` of :class:`.Factor` assignments with :meth:`~Analogy.unordered_comparison`.
 
         :param matchlist:
             possible ways to match generic :class:`.Factor`\s of
             ``need_matches`` with ``available``.
 
         :returns:
             a new version of ``matchlist`` filtered to be consistent with
-            ``self``\'s :meth:`~Relation.unordered_comparison`.
+            ``self``\'s :meth:`~Analogy.unordered_comparison`.
         """
         new_matchlist = []
         for matches in matchlist:

authorityspoke/rules.py

@@ -19,7 +19,7 @@
 from authorityspoke.context import get_directory_path
 from authorityspoke.enactments import Enactment
 from authorityspoke.factors import Factor, means, new_context_helper
-from authorityspoke.relations import Relation
+from authorityspoke.relations import Analogy
 
 
 @dataclass(frozen=True)
@@ -268,7 +268,7 @@ def contradicts_some_to_all(self, other: Procedure) -> bool:
 
         # For self to contradict other, every input of other
         # must be implied by some input or despite factor of self.
-        relations = (Relation(other.inputs, self_despite_or_input, operator.le),)
+        relations = (Analogy(other.inputs, self_despite_or_input, operator.le),)
         matchlist = self._all_relation_matches(relations)
 
         # For self to contradict other, some output of other
@@ -300,8 +300,8 @@ def implies_all_to_all(self, other: Procedure) -> bool:
             return True
 
         relations = (
-            Relation(other.outputs, self.outputs, operator.le),
-            Relation(self.inputs, other.inputs, operator.le),
+            Analogy(other.outputs, self.outputs, operator.le),
+            Analogy(self.inputs, other.inputs, operator.le),
         )
         matchlist = self._all_relation_matches(relations)
 
@@ -353,8 +353,8 @@ def implies_all_to_some(self, other: Procedure) -> bool:
         self_despite_or_input = (*self.despite, *self.inputs)
 
         relations = (
-            Relation(other.outputs, self.outputs, operator.le),
-            Relation(other.despite, self_despite_or_input, operator.le),
+            Analogy(other.outputs, self.outputs, operator.le),
+            Analogy(other.despite, self_despite_or_input, operator.le),
         )
 
         matchlist = self._all_relation_matches(relations)
@@ -389,9 +389,9 @@ def _implies_if_present(self, other: Factor) -> bool:
         despite_or_input = (*self.despite, *self.inputs)
 
         relations = (
-            Relation(other.outputs, self.outputs, operator.le),
-            Relation(other.inputs, self.inputs, operator.le),
-            Relation(other.despite, despite_or_input, operator.le),
+            Analogy(other.outputs, self.outputs, operator.le),
+            Analogy(other.inputs, self.inputs, operator.le),
+            Analogy(other.despite, despite_or_input, operator.le),
         )
 
         return bool(self._all_relation_matches(relations))
@@ -414,7 +414,7 @@ def means(self, other) -> bool:
         groups = ("outputs", "inputs", "despite")
         matchlist = [{}]
         for group in groups:
-            updater = Relation(
+            updater = Analogy(
                 need_matches=self.__dict__[group],
                 available=other.__dict__[group],
                 comparison=means,
@@ -426,7 +426,7 @@ def means(self, other) -> bool:
         # Now doing the same thing in reverse
         matchlist = [{}]
         for group in groups:
-            updater = Relation(
+            updater = Analogy(
                 need_matches=other.__dict__[group],
                 available=self.__dict__[group],
                 comparison=means,
@@ -456,21 +456,21 @@ def new_context(self, changes: Dict[Factor, Factor]) -> Procedure:
 
     @staticmethod
     def _all_relation_matches(
-        relations: Tuple[Relation, ...]
+        relations: Tuple[Analogy, ...]
     ) -> List[Dict[Factor, Optional[Factor]]]:
         """
-        Find all context registers consistent with multiple :class:`.Relation`\s.
+        Find all context registers consistent with multiple :class:`.Analogy`\s.
 
         :param relations:
-            a series of :class:`.Relation` comparisons in which
+            a series of :class:`.Analogy` comparisons in which
             the ``need_matches`` :class:`.Factor`\s all refer to
             one context (for instance, the same :class:`.Opinion`),
             and the ``available`` :class:`.Factor`\s all refer to
             another context.
 
         :returns:
             a list of all context registers consistent with all of the
-            :class:`.Relation`\s.
+            :class:`.Analogy`\s.
         """
         matchlist = [{}]
         for relation in relations:
@@ -498,7 +498,7 @@ def collection_from_dict(
         cls,
         case: Dict,
         mentioned: Optional[List[Factor]] = None,
-        regime: Optional["Regime"] = None
+        regime: Optional[Regime] = None
     ) -> List[Rule]:
         """
         Create a :py:class:`list` of :class:`Rule`\s from JSON.

docs/api/context.rst

@@ -1,9 +1,13 @@
-==============
+============================
 ``Context``
-==============
+============================
 
-.. autodecorator:: authorityspoke.factors.new_context_helper
+.. autodecorator:: authorityspoke.context.new_context_helper
 
 .. autodecorator:: authorityspoke.context.log_mentioned_context
 
-.. autofunction:: authorityspoke.context.get_directory_path
+``Analogies``
+================
+
+.. autoclass:: authorityspoke.relations.Analogy
+    :members:

docs/api/courts.rst

@@ -0,0 +1,6 @@
+==============
+``Courts``
+==============
+
+.. autoclass:: authorityspoke.courts.Court
+   :members:

docs/api/factors.rst

@@ -6,32 +6,92 @@
     :members:
     :special-members:
 
+``Entities``
+==============
+
+.. inheritance-diagram:: authorityspoke.factors.Entity
+    :top-classes: authorityspoke.factors.Factor
+    :parts: 1
+
+.. autoclass:: authorityspoke.factors.Entity
+    :members:
+    :special-members:
+
+``Facts``
+==============
+
 .. inheritance-diagram:: authorityspoke.factors.Fact
     :top-classes: authorityspoke.factors.Factor
     :parts: 1
 
 .. autoclass:: authorityspoke.factors.Fact
 
+``Exhibits``
+==============
+
 .. inheritance-diagram:: authorityspoke.factors.Exhibit
     :top-classes: authorityspoke.factors.Factor
     :parts: 1
 
 .. autoclass:: authorityspoke.factors.Exhibit
 
+``Evidence``
+==============
+
 .. inheritance-diagram:: authorityspoke.factors.Evidence
     :top-classes: authorityspoke.factors.Factor
     :parts: 1
 
 .. autoclass:: authorityspoke.factors.Evidence
 
+``Pleadings``
+==============
+
 .. inheritance-diagram:: authorityspoke.factors.Pleading
     :top-classes: authorityspoke.factors.Factor
     :parts: 1
 
 .. autoclass:: authorityspoke.factors.Pleading
 
+``Allegations``
+================
+
 .. inheritance-diagram:: authorityspoke.factors.Allegation
     :top-classes: authorityspoke.factors.Factor
     :parts: 1
 
 .. autoclass:: authorityspoke.factors.Allegation
+
+``Procedures``
+==============
+
+.. inheritance-diagram:: authorityspoke.rules.Procedure
+    :top-classes: authorityspoke.factors.Factor
+    :parts: 1
+
+.. autoclass:: authorityspoke.rules.Procedure
+    :members:
+    :special-members:
+    :private-members:
+
+``Rules``
+==============
+
+.. inheritance-diagram:: authorityspoke.rules.Rule
+    :top-classes: authorityspoke.factors.Factor
+    :parts: 1
+
+.. autoclass:: authorityspoke.rules.Rule
+    :members:
+    :special-members:
+
+``ProceduralRules``
+---------------------
+
+.. inheritance-diagram:: authorityspoke.rules.ProceduralRule
+    :top-classes: authorityspoke.factors.Factor
+    :parts: 1
+
+.. autoclass:: authorityspoke.rules.ProceduralRule
+    :members:
+    :special-members:

docs/api/legislation.rst

@@ -0,0 +1,19 @@
+===============
+``Legislation``
+===============
+
+``Codes``
+==============
+
+.. autoclass:: authorityspoke.enactments.Code
+    :members:
+    :special-members:
+
+.. autofunction:: authorityspoke.context.get_directory_path
+
+``Enactments``
+==============
+
+.. autoclass:: authorityspoke.enactments.Enactment
+    :members:
+    :special-members:

docs/api/regimes.rst

@@ -4,3 +4,9 @@
 
 .. autoclass:: authorityspoke.jurisdictions.Regime
     :members:
+
+``Jurisdictions``
+=================
+
+.. autoclass:: authorityspoke.jurisdictions.Jurisdiction
+    :members: