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,9 +232,8 @@ 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.
         """
         self.save_state(fname)

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,8 +145,9 @@ 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",...],
@@ -167,7 +168,9 @@ async def perform_test_from_obj(obj, router_factory) -> None:
                 ...
             ]
         }
-    NOTE: In adj_list, for any neighbors A and B, only list B as a neighbor of A
+
+    .. 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)
     """