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.

make

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 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 by running ./bin/sphinxbuilder. Alternatively, you can use Makefile targets:

docs-clean

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

docs-html

Build HTML

docs-linkcheck

Run linkcheck

docs-linkcheckbroken

Run linkcheck and show only broken links

docs-livehtml

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

docs-vale

Run spell, grammar, and style checks

docs

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