Fix all doc build warnings

Makefile

@@ -66,7 +66,7 @@ test-all:
 	tox
 
 build-docs:
-	sphinx-apidoc -o docs/ . setup.py "*conftest*"
+	sphinx-apidoc -o docs/ . setup.py "*conftest*" "libp2p/tools/interop*"
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(MAKE) -C docs doctest

docs/index.rst

@@ -11,6 +11,7 @@ Contents
 
     libp2p
     release_notes
+    examples
 
 
 Indices and tables

libp2p/__init__.py

@@ -55,7 +55,7 @@ def initialize_default_kademlia_router(
     :param alpha: The alpha parameter from the paper
     :param id_opt: optional id for host
     :param storage: An instance that implements
-        :interface:`~kademlia.storage.IStorage`
+        :class:`~kademlia.storage.IStorage`
     :return: return a default kademlia instance
     """
     if not id_opt:

libp2p/kademlia/network.py

@@ -232,10 +232,9 @@ class KademliaServer:
         """
         Save the state of node with a given regularity to the given filename.
 
-        Args:
+        :param fname: File name to save regularly to
-            fname: File name to save retularly to
+        :param frequency: Frequency in seconds that the state should be saved.
-            frequency: Frequency in seconds that the state should be saved.
+            By default, 10 minutes.
-                        By default, 10 minutes.
         """
         self.save_state(fname)
         loop = asyncio.get_event_loop()

libp2p/network/swarm.py

@@ -155,13 +155,15 @@ class Swarm(INetwork):
         :return: true if at least one success
 
         For each multiaddr
-            Check if a listener for multiaddr exists already
+
-            If listener already exists, continue
+          - Check if a listener for multiaddr exists already
-            Otherwise:
+          - If listener already exists, continue
-                Capture multiaddr in conn handler
+          - Otherwise:
-                Have conn handler delegate to stream handler
+
-                Call listener listen with the multiaddr
+              - Capture multiaddr in conn handler
-                Map multiaddr to listener
+              - Have conn handler delegate to stream handler
+              - Call listener listen with the multiaddr
+              - Map multiaddr to listener
         """
         for maddr in multiaddrs:
             if str(maddr) in self.listeners:

libp2p/tools/pubsub/floodsub_integration_test_settings.py

@@ -145,31 +145,34 @@ floodsub_protocol_pytest_params = [
 
 async def perform_test_from_obj(obj, router_factory) -> None:
     """
-    Perform pubsub tests from a test obj.
+    Perform pubsub tests from a test object, which is composed as follows:
-    test obj are composed as follows:
 
-    {
+    .. code-block:: python
-        "supported_protocols": ["supported/protocol/1.0.0",...],
+
-        "adj_list": {
+        {
-            "node1": ["neighbor1_of_node1", "neighbor2_of_node1", ...],
+            "supported_protocols": ["supported/protocol/1.0.0",...],
-            "node2": ["neighbor1_of_node2", "neighbor2_of_node2", ...],
+            "adj_list": {
-            ...
+                "node1": ["neighbor1_of_node1", "neighbor2_of_node1", ...],
-        },
+                "node2": ["neighbor1_of_node2", "neighbor2_of_node2", ...],
-        "topic_map": {
+                ...
-            "topic1": ["node1_subscribed_to_topic1", "node2_subscribed_to_topic1", ...]
-        },
-        "messages": [
-            {
-                "topics": ["topic1_for_message", "topic2_for_message", ...],
-                "data": b"some contents of the message (newlines are not supported)",
-                "node_id": "message sender node id"
             },
-            ...
+            "topic_map": {
-        ]
+                "topic1": ["node1_subscribed_to_topic1", "node2_subscribed_to_topic1", ...]
-    }
+            },
-    NOTE: In adj_list, for any neighbors A and B, only list B as a neighbor of A
+            "messages": [
-    or B as a neighbor of A once. Do NOT list both A: ["B"] and B:["A"] as the behavior
+                {
-    is undefined (even if it may work)
+                    "topics": ["topic1_for_message", "topic2_for_message", ...],
+                    "data": b"some contents of the message (newlines are not supported)",
+                    "node_id": "message sender node id"
+                },
+                ...
+            ]
+        }
+
+    .. note::
+        In adj_list, for any neighbors A and B, only list B as a neighbor of A
+        or B as a neighbor of A once. Do NOT list both A: ["B"] and B:["A"] as the behavior
+        is undefined (even if it may work)
     """
 
     # Step 1) Create graph