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

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

make help

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.

./bin/test -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 black

Use the following command to run tests.

make test
Contents