From 72b07732f24b4930cdadb3c6dcfdaad394d4ba7f Mon Sep 17 00:00:00 2001
From: Pradyun Gedam <pradyunsg@users.noreply.github.com>
Date: Tue, 31 Aug 2021 18:04:58 +0100
Subject: [PATCH] Rewrite API documentation example

Make it a little more realisitic and include a longer signature too.
---
 docs/kitchen-sink/demo_py/furo_demo_module.py | 57 ++++++++++++++-----
 1 file changed, 42 insertions(+), 15 deletions(-)

diff --git a/docs/kitchen-sink/demo_py/furo_demo_module.py b/docs/kitchen-sink/demo_py/furo_demo_module.py
index a9c321e89..7b8a9c214 100644
--- a/docs/kitchen-sink/demo_py/furo_demo_module.py
+++ b/docs/kitchen-sink/demo_py/furo_demo_module.py
@@ -3,26 +3,53 @@
 autodoc, and other related functionality.
 """
 
+from typing import Optional, TextIO, Type, Union
 
-class Foo:
+
+def show_warning(
+    message: Union[Warning, str],
+    category: Type[Warning],
+    filename: str,
+    lineno: int,
+    file: Optional[TextIO] = None,
+    line: Optional[str] = None,
+) -> None:
+    """Show a warning to the end user.
+
+    :param message: What you want to tell the user.
+    :param category: The type of warning.
+    :param filename: The file that the warning is for.
+    :param lineno: The line that the warning is for.
+    :param file: Where to write the warning.
+    :param line: line of source code to be included in the warning message
     """
-    A demo class of type Foo.
 
-    Has a method baz() returning ints.
+
+class RandomNumberGenerator:
+    """A random number generator.
+
+    You can use this as follows.
+
+    .. code-block:: python
+
+       RNG = RandomNumberGenerator()
+       print(RNG.get_random_integer())
+
+    This is hopefully useful to somebody.
     """
 
-    def baz(self) -> int:
-        """
-        Return a random integer.
-        See also: https://xkcd.com/221/
+    @property
+    def seed(self):
+        """The seed for random number generation.
+
+        .. seealso:: https://xkcd.com/221/
         """
-        return 3
+        return 4
 
+    def get_random_integer(self) -> int:
+        """Return a random integer."""
+        return self.seed
 
-def bar(f: Foo) -> Foo:
-    """
-    the identity function, but only for Foos
-    """
-    if isinstance(f, Foo):
-        return f
-    raise TypeError("Expected a Foo!")
+    def get_random_float(self) -> float:
+        """Return a random float."""
+        return float(self.seed)