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:

..  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 ./bin/sphinxbuilder.

Make sure you add and commit the generated files in http-examples.