display example code and usage instructions in docs

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:

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:

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
 ---------------

examples/chat/chat.py

@@ -53,10 +53,9 @@ async def stream_handler(stream: INetStream) -> 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...")
 

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()

newsfragments/466.docs.rst

@@ -0,0 +1 @@
+Display example usage and full code in docs

setup.py

@@ -68,7 +68,6 @@
     # added during debugging
     "anyio",
     "p2pclient",
-    "mypy-protobuf",
 ]