Make example paths shorter & get markdown example better

docs/compatibility/pydantic.md

@@ -1,8 +1,13 @@
 ---
 title: 🟡 pydantic
+hide:
+  - toc
 ---
 
-!!! warning "Partially compatible"
-    Pydantic models will raise an error if to try to inherit them from `Exception`, but we can use Pydantic `dataclasses` instead. Idea:  [:simple-github: pydantic/pydantic#1875](https://github.com/pydantic/pydantic/issues/1875)
+!!! info inline end "Idea"
+    [:simple-github: pydantic/pydantic#1875](https://github.com/pydantic/pydantic/issues/1875)
+
+* :slight_frown: Pydantic models will raise an error if to try to inherit them from `Exception` and then `raise`,
+* :slight_smile: but we can use Pydantic `dataclasses` instead.
 
 {{ run_python_script("examples/pydantic_exception.py") }}

docs/compatibility/rich.md

@@ -1,36 +1,22 @@
 ---
 title: 🟡 rich
+hide:
+  - toc
 ---
 
 ## 🟢 `Documented`
 
-```python
-import rich
-from documented import Documented
-
-
-class MyMessage(Documented):
-    """
-    This is a Markdown formatted message.
-    
-    * _One_,
-    * *Two*,
-    * `Three`
-    
-    and **more** features of Markdown
-    
-    > are supported.
-    """
-
-rich.print(MyMessage())
-```
+{{ run_python_script("examples/rich-markdown.py") }}
 
 This will render the docstring as Markdown in the console.
 
 ## 🟡 `DocumentedError`
 
-It's easy to write an exception with console markup or Markdown formatted text, catch that exception and `rich.print()` it for user's information.
+!!! info inline end "See related thread"
+    [:simple-github: textualize/rich#2619](https://github.com/Textualize/rich/issues/2619)
 
-I haven't found a way to integrate [:simple-github: rich](https://github.com/textualize/rich/) with `documented` directly, to render beautiful exceptions with console markup or Markdown text in them right in the traceback.
+* :slight_frown: I haven't found a way to integrate [:simple-github: rich](https://github.com/textualize/rich/) with `documented` directly, to render beautiful exceptions with console markup or Markdown text in them right in the traceback.
 
-Related thread: [:simple-github: textualize/rich#2619](https://github.com/Textualize/rich/issues/2619).
+* :slight_smile: However, this can always be done manually:
+    * `except` the error,
+    * and `rich.print()` it.

docs/examples/pydantic_exception.py

@@ -6,7 +6,9 @@
 @pydantic_dataclass
 class PydanticError(DocumentedError):
     """
-    Incorrect answer to the Question of Life, Universe, and Everything.
+    Incorrect answer!
+
+    (To the Question of Life, Universe, and Everything.)
 
         - Answer given: {self.answer}
         - Correct answer: indubitably 42.
@@ -15,4 +17,4 @@ class PydanticError(DocumentedError):
     answer: str
 
 
-raise PydanticError(answer='bazinga')
+raise PydanticError(answer='bebebe')

docs/examples/rich-markdown.py

@@ -0,0 +1,19 @@
+import rich
+from documented import Documented
+
+
+class MyMessage(Documented):
+    """
+    # This is a Markdown formatted message.
+
+    * _One_,
+    * *Two*,
+    * `Three`
+
+    and **more** features of Markdown
+
+    > are supported.
+    """
+
+
+rich.print(MyMessage())

macros.py

@@ -1,13 +1,15 @@
 """MkDocs macros for the documentation site."""
 import functools
+import os
+import re
 from pathlib import Path
 
 from mkdocs_macros.plugin import MacrosPlugin
 from sh import python, ErrorReturnCode
 
 
 TEMPLATE = """
-<div class="side-by-side" markdown>
+<div class="side-by-side" style="max-width: 100%" markdown>
 <div class="admonition info" markdown>
 <p class="admonition-title" markdown>{path}</p>
 ```python
@@ -37,6 +39,11 @@ def format_annotations(annotations: list[str]) -> str:
     )
 
 
+def replace_full_file_path(line: str, code_path: Path) -> str:
+    """Replace full file path with its absolute path, for conciseness."""
+    return line.replace(str(code_path.parent.absolute()), '📂')
+
+
 def run_python_script(
     path: str,
     docs_dir: Path,
@@ -53,7 +60,14 @@ def run_python_script(
     code = code_path.read_text()
 
     try:
-        stdout, stderr = python(*args, code_path), None
+        stdout, stderr = python(
+            *args,
+            code_path,
+            _env={
+                **os.environ,
+                'TERM': 'dumb',
+            },
+        ), None
     except ErrorReturnCode as err:
         stdout = err.stdout.decode()
         stderr = err.stderr.decode()
@@ -65,6 +79,11 @@ def run_python_script(
 
     output = '\n'.join(filter(bool, [stdout, stderr]))
 
+    output = '\n'.join(
+        replace_full_file_path(line=line, code_path=code_path)
+        for line in output.splitlines()
+    )
+
     return TEMPLATE.format(
         path=path,
         code=code,