Contributing to plone.restapi#

We use GNU make when developing plone.restapi. To install this package, its dependencies, and its documentation, code formatting, and testing tools, run the following command in the root of the project.


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.

Code formatting and testing#

To ensure consistent code formatting, we use Black. All pull requests must pass code formatting checks. We recommend that you run Black locally. You can use the following command to automatically format the code.

make black

To run tests locally and ensure your changes don't introduce any issues, use the following command. This will execute the test suite and provide test feedback.

make test