Contribute to plone.restapi

Contribute to plone.restapi#

This section describes how to contribute to the plone.restapi project. It extends Contributing to Plone.

Prerequisites#

Prepare your system by installing Prerequisites.

Set up development environment#

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.

make install

To see all the Makefile targets and help, use the following command.

make help

Start Plone#

make start

Run frontend tests against the acceptance server#

To test a frontend against your local plone.restapi checkout, install the development environment with make install, then start the acceptance server. Use Plone 6 with plone.app.robotframework 2 or later for this server.

make acceptance-backend-start

Wait for Started Zope robot server, then configure your frontend tests to use http://localhost:55001/plone as their API URL. The server uses the REST API Dexterity test fixture and a single WSGI worker thread. Authenticate as admin with the password secret to manage the test site.

To check that the API responds, run the following command in another terminal.

curl --fail --user admin:secret --header 'Accept: application/json' \
  http://localhost:55001/plone/@types

Stop the server with Control+C when you finish. Restart it to recreate the site and discard all changes.

Generate documentation examples#

This documentation includes examples of requests and responses, using each of 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.

.venv/bin/zope-testrunner --test-path=src -t test_documentation_search_fullobjects

The above command also generates the request and the response files in tests/http-examples/. Include them in the documentation using MyST syntax.

```{eval-rst}
..  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.

make docs-livehtml

Add and commit the generated files in src/plone/restapi/tests/http-examples/.

Documentation checks#

Run a link checker on documentation.

make docs-linkcheckbroken

Run a spelling, grammar, and style checker on documentation.

make docs-vale

Conventions#

Code formatting and testing#

All changes must pass code formatting and tests. Run these checks locally before creating a pull request.

Use the following command to automatically format the code with Black.

make check

Use the following command to run tests.

make test
Contents