doc: fix and improve documentation

csernazs · csernazs · commit 8b7ae468fea9 · 2019-03-09T11:11:48.000+01:00
Fix links, add a bit of a text to the guide, and update api.rst to have
proper links to the classes in the TOC.
diff --git a/doc/api.rst b/doc/api.rst
@@ -1,11 +1,41 @@
 API documentation
 =================
 
+pytest_httpserver
+-----------------
+
 .. automodule:: pytest_httpserver
 
+HTTPServer
+~~~~~~~~~~
+
     .. autoclass:: HTTPServer
         :members:
 
+WaitingSettings
+~~~~~~~~~~~~~~~
+
+    .. autoclass:: WaitingSettings
+        :members:
+
+HeaderValueMatcher
+~~~~~~~~~~~~~~~~~~
+
+    .. autoclass:: HeaderValueMatcher
+        :members:
+
+RequestHandler
+~~~~~~~~~~~~~~
+
+    .. autoclass:: RequestHandler
+        :members:
+
+
+pytest_httpserver.httpserver
+----------------------------
+This module contains some internal classes which are normally not instantiated
+by the user.
+
 .. automodule:: pytest_httpserver.httpserver
 
     .. autoclass:: RequestMatcher
@@ -20,12 +50,6 @@ API documentation
     .. autoclass:: pytest_httpserver.httpserver.HTTPServerError
         :members:
 
-    .. autoclass:: pytest_httpserver.httpserver.HeaderValueMatcher
-        :members:
-
-    .. autoclass:: pytest_httpserver.httpserver.RequestHandler
-        :members:
-
     .. autoclass:: pytest_httpserver.httpserver.RequestHandlerList
         :members:
 
diff --git a/doc/guide.rst b/doc/guide.rst
@@ -50,6 +50,13 @@ When dealing with static responses you can determine all parts of the http respo
 content, etc), and you can also specify a JSON-serializable object to be returned as a json.
 
 
+Waiting for test completion or errors
+-------------------------------------
+It is possible to wait until all oneshot and ordered handlers are exhausted or any error happened. This
+is provided by a context manager which waits until one of these events occured. This can be further customized
+by :py:class:`pytest_httpserver.server.WaitSettings` object to raise or not raise assertion.
+
+
 Debugging errors while testing
 ------------------------------
 When the tests are running against the server and no matcher can be found for the given request, the server
diff --git a/doc/index.rst b/doc/index.rst
@@ -34,7 +34,7 @@ Example
 For further details, please read the :doc:`guide` or the :doc:`api`.
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     guide
     api
diff --git a/pytest_httpserver/httpserver.py b/pytest_httpserver/httpserver.py
@@ -615,8 +615,8 @@ def start(self):
         program needs to be terminated by Ctrl+C or by signal as it will not terminate until
         the thred is stopped.
 
-        If the sever is already running :py:class`HTTPServerError` will be raised. If you are
-        unsure, call :py:meth`is_running` first.
+        If the sever is already running :py:class:`HTTPServerError` will be raised. If you are
+        unsure, call :py:meth:`is_running` first.
 
         There's a context interface of this class which stops the server when the context block ends.
         """
@@ -799,6 +799,9 @@ def wait(self, raise_assertions: Optional[bool] = None, stop_on_nohandler: Optio
         :param timeout: time (in seconds) until time is out
 
         Example:
+
+        .. code-block:: python
+
             def test_wait(httpserver):
                 httpserver.expect_oneshot_request('/').respond_with_data('OK')
                 with httpserver.wait(raise_assertions=False, stop_on_nohandler=False, timeout=1) as waiting:
