document generating the documentation snippets

docs/source/contributing.rst

@@ -0,0 +1,28 @@
+Contributing to plone.restapi
+=============================
+
+Generating documentation examples
+---------------------------------
+
+This documentation includes examples of requests and responses (http, curl, httpie and python-requests).
+These examples are generated by the documentation tests in ``test_documentation.py``.
+To generate a new example, add a new test case to `test_documentation.py` - for example ``test_documentation_search_fullobjects``, and run the test:
+
+``./bin/test -t test_documentation_search_fullobjects``
+
+This generates the request and the response files in ``tests/http-examples/``.
+
+Include them in the documentation like this:
+
+.. code-block:: ReST
+
+    ..  http:example:: curl httpie python-requests
+        :request: ../../src/plone/restapi/tests/http-examples/search_fullobjects.req
+
+    .. literalinclude:: ../../src/plone/restapi/tests/http-examples/search_fullobjects.resp
+       :language: http
+
+
+Build the sphinx docs locally to test the rendering by running ``make html`` in the docs folder.
+
+Make sure you add and commit the generated files in ``http-examples``.

docs/source/index.rst

@@ -53,6 +53,7 @@ Contents
    i18n
    email-notification
    upgrade-guide
+   contributing
 
 .. include:: ../../README.rst