doc: major reorg + user guide

csernazs · csernazs · commit 0c418ba4a361 · 2018-08-18T13:50:50.000+02:00
diff --git a/doc/changes.rst b/doc/changes.rst
@@ -0,0 +1,2 @@
+.. release-notes:: Release Notes
+
diff --git a/doc/conf.py b/doc/conf.py
@@ -31,7 +31,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'reno.sphinxext',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/doc/guide.rst b/doc/guide.rst
@@ -0,0 +1,16 @@
+
+User's Guide
+============
+
+Starting and stopping the server
+--------------------------------
+The server can be started by instatiating it and then calling the
+:py:meth:`pytest_httpserver.HTTPServer.start` method. This will start the server in a separate
+thread, so you will need to make sure that the :py:meth:`pytest_httpserver.HTTPServer.stop` method
+is called before your code exits.
+
+A free TCP port needs to be specified when instantiating the server, where no other daemon is listening.
+
+If you are using the pytest plugin it is done automatically by the plugin. Possibility to change
+the TCP port in this case is TBD.
+
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,11 +1,7 @@
-.. pytest_httpserver documentation master file, created by
-   sphinx-quickstart on Sat Aug 11 08:07:37 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
+pytest-httpserver
+=================
 
-User's Guide
-------------
 pytest-httpserver is a python package which allows you to start a real HTTP server
 for your tests. The server can be configured programmatically to how to respond to
 requests.
@@ -22,8 +18,9 @@ This library can be used with pytest in the most convenient way but if you prefe
 other test frameworks, you can still use it with the context API or by writing a wrapper
 for it.
 
-Example with pytest
--------------------
+
+Example
+-------
 
 .. code:: python
 
@@ -34,44 +31,11 @@ Example with pytest
         assert requests.get(httpserver.url_for("/foobar")).json() == {'foo': 'bar'}
 
 
-Example without pytest
-----------------------
-
-.. code:: python
-
-    import requests
-    import unittest
-    from pytest_httpserver import HTTPServer
-
-    class TestJSONClient(unittest.TestCase):
-        def setUp(self):
-            self.httpserver = HTTPServer()
-            self.httpserver.start()
-
-        def test_json_client(self):
-            self.httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"})
-            self.assertEqual(requests.get(self.httpserver.url_for("/foobar")).json(), {'foo': 'bar'})
-
-        def tearDown(self):
-            self.httpserver.stop()
-
-
-API Reference
--------------
-
-If you are looking for information on a specific function, class or
-method, this part of the documentation is for you.
+For further details, please read the :doc:`guide` or the :doc:`api`.
 
 .. toctree::
-   :maxdepth: 2
-
-   api
-
-
-
-Indices and tables
-==================
+    :maxdepth: 1
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    guide
+    api
+    changes

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+.. release-notes:: Release Notes`
	`2`	`+`