From 7de6cbaab0d105f5062a072a38b08560a4a6ffbe Mon Sep 17 00:00:00 2001
From: pacrob <5199899+pacrob@users.noreply.github.com>
Date: Sun, 19 May 2024 12:37:25 -0600
Subject: [PATCH] display example code and usage instructions in docs

---
 docs/examples.chat.rst     | 30 ++++++++++++++----------------
 docs/examples.echo.rst     | 18 ++++++++++++++++++
 docs/examples.rst          | 13 +++++++++----
 examples/chat/chat.py      |  7 +++----
 examples/echo/__init__.py  |  0
 examples/echo/echo.py      |  7 +++----
 newsfragments/466.docs.rst |  1 +
 setup.py                   |  1 -
 8 files changed, 48 insertions(+), 29 deletions(-)
 create mode 100644 docs/examples.echo.rst
 create mode 100644 examples/echo/__init__.py
 create mode 100644 newsfragments/466.docs.rst

diff --git a/docs/examples.chat.rst b/docs/examples.chat.rst
index 5c149bef..728858b7 100644
--- a/docs/examples.chat.rst
+++ b/docs/examples.chat.rst
@@ -1,21 +1,19 @@
-examples.chat package
-=====================
+Chat Demo
+=========
 
-Submodules
-----------
+Copy the code below into a file called ``chat.py``.
+Install dependencies, preferably in a virtual environment, with:
 
-examples.chat.chat module
--------------------------
+.. code-block:: bash
 
-.. automodule:: examples.chat.chat
-   :members:
-   :undoc-members:
-   :show-inheritance:
+    python -m pip install libp2p
 
-Module contents
----------------
 
-.. automodule:: examples.chat
-   :members:
-   :undoc-members:
-   :show-inheritance:
+Run the demo with ``python chat.py`` and copy the output.
+
+Open a second terminal, navigate to the folder that contains ``chat.py``, then paste
+and run the copied line.
+
+.. literalinclude:: ../examples/chat/chat.py
+    :language: python
+    :linenos:
diff --git a/docs/examples.echo.rst b/docs/examples.echo.rst
new file mode 100644
index 00000000..12bd1eae
--- /dev/null
+++ b/docs/examples.echo.rst
@@ -0,0 +1,18 @@
+Echo Demo
+=========
+
+Copy the code below into a file called ``demo.py``.
+Install dependencies, preferably in a virtual environment, with:
+
+.. code-block:: bash
+
+    python -m pip install libp2p
+
+Run the demo with ``python echo.py`` and copy the output.
+
+Open a second terminal, navigate to the folder that contains ``echo.py``, then paste
+and run the copied line.
+
+.. literalinclude:: ../examples/echo/echo.py
+    :language: python
+    :linenos:
diff --git a/docs/examples.rst b/docs/examples.rst
index 4dd05984..04b4917a 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,12 +1,17 @@
-examples package
-================
+Examples
+========
 
-Subpackages
------------
+These are functional demonstrations of aspects of the library. They are
+intended to be run as scripts, and are not intended to be used as part of
+another application.
+
+Example Scripts
+---------------
 
 .. toctree::
 
     examples.chat
+    examples.echo
 
 Module contents
 ---------------
diff --git a/examples/chat/chat.py b/examples/chat/chat.py
index 7c6b2fed..6496f1dd 100755
--- a/examples/chat/chat.py
+++ b/examples/chat/chat.py
@@ -53,10 +53,9 @@ async def run(port: int, destination: str) -> None:
             host.set_stream_handler(PROTOCOL_ID, stream_handler)
 
             print(
-                f"Run 'python ./examples/chat/chat.py "
-                f"-p {int(port) + 1} "
-                f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}' "
-                "on another console."
+                "Run this from the same folder in another console:\n\n"
+                f"python chat.py -p {int(port) + 1} "
+                f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}\n"
             )
             print("Waiting for incoming connection...")
 
diff --git a/examples/echo/__init__.py b/examples/echo/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/examples/echo/echo.py b/examples/echo/echo.py
index d9039715..75259843 100644
--- a/examples/echo/echo.py
+++ b/examples/echo/echo.py
@@ -52,10 +52,9 @@ async def run(port: int, destination: str, seed: int = None) -> None:
             host.set_stream_handler(PROTOCOL_ID, _echo_stream_handler)
 
             print(
-                f"Run 'python ./examples/echo/echo.py "
-                f"-p {int(port) + 1} "
-                f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}' "
-                "on another console."
+                "Run this from the same folder in another console:\n\n"
+                f"python echo.py -p {int(port) + 1} "
+                f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}\n"
             )
             print("Waiting for incoming connections...")
             await trio.sleep_forever()
diff --git a/newsfragments/466.docs.rst b/newsfragments/466.docs.rst
new file mode 100644
index 00000000..9209bf81
--- /dev/null
+++ b/newsfragments/466.docs.rst
@@ -0,0 +1 @@
+Display example usage and full code in docs
diff --git a/setup.py b/setup.py
index b099687a..62f33ab3 100644
--- a/setup.py
+++ b/setup.py
@@ -68,7 +68,6 @@ install_requires = [
     # added during debugging
     "anyio",
     "p2pclient",
-    "mypy-protobuf",
 ]