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 To generate a new example, add a new test case to, 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 using MyST syntax:

..  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 documentation locally to test the rendering by running ./bin/sphinxbuilder. Alternatively, you can use Makefile targets:


Clean current and legacy docs build directories, and Python virtual environment


Build HTML


Run linkcheck


Run linkcheck and show only broken links


Rebuild Sphinx documentation on changes, with live-reload in the browser


Run spell, grammar, and style checks


Build Docs

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