docs: strip doctest blocks from the API reference + cleaner rendering

Beautification of the generated Sphinx site:
- autodoc-process-docstring hook removes the doctest (>>> ...) example blocks
  from the rendered pages (and any now-dangling 'Example:' lead-in). The examples
  stay in the source docstrings (still runnable / readable in the code) -- they
  just no longer clutter the HTML API reference as interactive-session dumps.
- add_module_names = False: members render as 'expr()' instead of
  'aima.utils.expr()' -- shorter, cleaner headings.
- minor napoleon tweaks (no rtype block, ivar style).

Build stays at 0 warnings.

Author: dmeoli

docs/conf.py

@@ -6,6 +6,7 @@
 """
 
 import os
+import re
 import sys
 
 # make the library importable for autodoc
@@ -56,6 +57,54 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# show members as ``expr()`` rather than ``aima.utils.expr()`` -- cleaner headings
+add_module_names = False
+
+# napoleon: render Google/NumPy-style sections a bit more compactly
+napoleon_use_rtype = False
+napoleon_use_ivar = True
+
+
+def _strip_doctests(app, what, name, obj, options, lines):
+    """Drop doctest (``>>> ...``) example blocks from the rendered API docs.
+
+    The examples stay in the source docstrings (useful when reading the code or
+    running them as doctests); they are merely omitted from the HTML so the API
+    reference reads as clean prose instead of interactive-session transcripts.
+    """
+    cleaned, in_block = [], False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith(">>>"):
+            if not in_block:
+                # also drop a now-dangling "Example:"/"Examples:" header + blanks
+                while cleaned and (not cleaned[-1].strip()
+                                   or cleaned[-1].strip().rstrip(":").lower()
+                                   in ("example", "examples", "for example")):
+                    cleaned.pop()
+                # also drop a trailing "... Example:" sentence on the prose line
+                if cleaned:
+                    cleaned[-1] = re.sub(
+                        r"\.\s+(for example|examples?|e\.g\.)\s*:?\s*$", ".",
+                        cleaned[-1], flags=re.I)
+                in_block = True
+            continue
+        if in_block:
+            if not stripped:            # a blank line ends the doctest block
+                in_block = False
+                cleaned.append(line)
+            # otherwise: a ``...`` continuation or an expected-output line -> drop
+            continue
+        cleaned.append(line)
+    while cleaned and not cleaned[-1].strip():
+        cleaned.pop()
+    lines[:] = cleaned
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", _strip_doctests)
+
+
 # -- HTML output -------------------------------------------------------------
 
 html_theme = "sphinx_rtd_theme"