Remove unnecessary paths from Sphinx directives. (#132)

* remove unnecessary paths from Sphinx directives.

* remove full alias autodoc from documentation.

* work around mypy issue python/mypy#6700.

docs/api/actions.rst

@@ -24,11 +24,30 @@ Debug
 .. autoclass:: Debug
     :members:
 
+Either
+------
+
+**Aliases**: ``Attempt``,
+``AttemptTo``,
+``GoFor``,
+``Try``
+``TryTo``,
+``Attempts``,
+``AttemptsTo``,
+``GoesFor``,
+``Tries``,
+``TriesTo``
+
+.. autoclass:: Either
+    :members:
+    :exclude-members: except_, else_, otherwise, alternatively, failing_that
+
 Eventually
 ----------
 
 .. autoclass:: Eventually
     :members:
+    :exclude-members: trying_for_no_longer_than, trying_for, waiting_for, polling_every, trying_every
 
 Log
 ---
@@ -45,6 +64,7 @@ MakeNote
 
 .. autoclass:: MakeNote
     :members:
+    :exclude-members: of_the
 
 Pause
 -----
@@ -55,6 +75,7 @@ Pause
 
 .. autoclass:: Pause
     :members:
+    :exclude-members: second_because,
 
 See
 ---
@@ -112,21 +133,3 @@ Silently
 **Aliases**: ``Quietly``
 
 .. autofunction:: Silently
-
-
-Either
-------
-
-**Aliases**: ``Attempt``,
-``AttemptTo``,
-``GoFor``,
-``Try``
-``TryTo``,
-``Attempts``,
-``AttemptsTo``,
-``GoesFor``,
-``Tries``,
-``TriesTo``
-
-.. autoclass:: Either
-    :members:

docs/api/actors.rst

@@ -4,3 +4,10 @@ Actor API
 
 .. autoclass:: screenpy.actor.Actor
     :members:
+    :exclude-members:
+        can,
+        with_ordered_cleanup_tasks, with_independent_cleanup_tasks,
+        ability_to,
+        was_able_to, did, will, tries_to, tried_to, tries, tried, does, should, shall
+        perform,
+        exit_stage_left, exit_stage_right, exit_through_vomitorium

screenpy/actions/either.py

@@ -25,7 +25,7 @@ class Either:
 
     By default, ``Either`` catches AssertionErrors, so you can use
     :class:`~screenpy.actions.See` to decide which path to follow. Use the
-    :meth:`~screenpy.actions.Either.ignoring` method to ignore other exceptions.
+    :meth:`ignoring` method to ignore other exceptions.
 
     Examples::
 
@@ -46,33 +46,15 @@ class Either:
     except_performables: tuple[Performable, ...]
     ignore_exceptions: tuple[type[BaseException], ...]
 
-    def perform_as(self, the_actor: Actor) -> None:
-        """Direct the Actor to perform one of two performances."""
-        # kinking the cable before the attempt
-        # avoids explaning what the actor tries to do.
-        # logs the first attempt only if it succeeds
-        # or if UNABRIDGED_NARRATION is enabled
-        with the_narrator.mic_cable_kinked():
-            try:
-                the_actor.will(*self.try_performables)
-            except self.ignore_exceptions:
-                if not settings.UNABRIDGED_NARRATION:
-                    the_narrator.clear_backup()
-            else:
-                return
-
-        the_actor.will(*self.except_performables)
-        return
-
     def or_(self, *except_performables: Performable) -> Self:
         """Provide the alternative routine to perform.
 
         Aliases:
-            * :meth:`~screenpy.actions.Either.except_`
-            * :meth:`~screenpy.actions.Either.else_`
-            * :meth:`~screenpy.actions.Either.otherwise`
-            * :meth:`~screenpy.actions.Either.alternatively`
-            * :meth:`~screenpy.actions.Either.failing_that`
+            * ``except_``
+            * ``else_``
+            * ``otherwise``
+            * ``alternatively``
+            * ``failing_that``
         """
         self.except_performables = except_performables
         return self
@@ -95,6 +77,24 @@ def describe(self) -> str:
 
         return f"Either {try_summary} or {except_summary}"
 
+    def perform_as(self, the_actor: Actor) -> None:
+        """Direct the Actor to perform one of two performances."""
+        # kinking the cable before the attempt
+        # avoids explaning what the actor tries to do.
+        # logs the first attempt only if it succeeds
+        # or if UNABRIDGED_NARRATION is enabled
+        with the_narrator.mic_cable_kinked():
+            try:
+                the_actor.will(*self.try_performables)
+            except self.ignore_exceptions:
+                if not settings.UNABRIDGED_NARRATION:
+                    the_narrator.clear_backup()
+            else:
+                return
+
+        the_actor.will(*self.except_performables)
+        return
+
     def __init__(self, *first: Performable) -> None:
         self.try_performables: tuple[Performable, ...] = first
         self.ignore_exceptions = (AssertionError,)

screenpy/actions/eventually.py

@@ -81,41 +81,25 @@ def for_(self, amount: float) -> _TimeframeBuilder:
         """Set for how long the actor should continue trying.
 
         Aliases:
-            * :meth:`~screenpy.actions.Eventually.trying_for_no_longer_than`
-            * :meth:`~screenpy.actions.Eventually.trying_for`
-            * :meth:`~screenpy.actions.Eventually.waiting_for`
+            * ``trying_for_no_longer_than``
+            * ``trying_for``
+            * ``waiting_for``
         """
         return self._TimeframeBuilder(self, amount, "timeout")
 
-    def trying_for_no_longer_than(self, amount: float) -> _TimeframeBuilder:
-        """Alias for :meth:`~screenpy.actions.Eventually.for_`."""
-        return self.for_(amount)
-
-    def trying_for(self, amount: float) -> _TimeframeBuilder:
-        """Alias for :meth:`~screenpy.actions.Eventually.for_`."""
-        return self.for_(amount)
-
-    def waiting_for(self, amount: float) -> _TimeframeBuilder:
-        """Alias for :meth:`~screenpy.actions.Eventually.for_`."""
-        return self.for_(amount)
+    trying_for_no_longer_than = trying_for = waiting_for = for_
 
     def polling(self, amount: float) -> _TimeframeBuilder:
         """Adjust the polling frequency.
 
         Aliases:
-            * :meth:`~screenpy.actions.Eventually.polling_every`
-            * :meth:`~screenpy.actions.Eventually.trying_every`
+            * ``polling_every``
+            * ``trying_every``
         """
         self.poll = amount
         return self._TimeframeBuilder(self, amount, "poll")
 
-    def polling_every(self, amount: float) -> _TimeframeBuilder:
-        """Alias for :meth:`~screenpy.actions.Eventually.polling`."""
-        return self.polling(amount)
-
-    def trying_every(self, amount: float) -> _TimeframeBuilder:
-        """Alias for :meth:`~screenpy.actions.Eventually.polling`."""
-        return self.polling(amount)
+    polling_every = trying_every = polling
 
     @property
     def performable_to_log(self) -> str:

screenpy/actions/make_note.py

@@ -44,13 +44,16 @@ def of(cls, question: T_Q) -> Self:
         """Supply the Question to answer and its arguments.
 
         Aliases:
-            * :meth:`~screenpy.actions.MakeNote.of_the`
+            * ``of_the``
         """
         return cls(question)
 
     @classmethod
     def of_the(cls, question: T_Q) -> Self:
-        """Alias for :meth:`~screenpy.actions.MakeNote.of`."""
+        """Alias for :meth:`of`.
+
+        Workaround for https://github.com/python/mypy/issues/6700
+        """
         return cls.of(question)
 
     def as_(self, key: str) -> Self:

screenpy/actions/pause.py

@@ -50,15 +50,13 @@ def seconds_because(self, reason: str) -> Self:
         """Use seconds and provide a reason for the pause.
 
         Aliases:
-            * :meth:`~screenpy.actions.Pause.second_because`
+            * ``second_because``
         """
         self.unit = f"second{'s' if self.number != 1 else ''}"
         self.reason = self._massage_reason(reason)
         return self
 
-    def second_because(self, reason: str) -> Self:
-        """Alias for :meth:`~screenpy.actions.Pause.seconds_because`."""
-        return self.seconds_because(reason)
+    second_because = seconds_because
 
     def milliseconds_because(self, reason: str) -> Self:
         """Use milliseconds and provide a reason for the pause."""