---
myst:
  html_meta:
    "description": "Contribute to plone.restapi"
    "property=og:description": "Contribute to plone.restapi"
    "property=og:title": "Contribute to plone.restapi"
    "keywords": "Plone, plone.restapi, REST, API, contribute, documentation"
---

# Contribute to `plone.restapi`

This section describes how to contribute to the `plone.restapi` project.
It extends {doc}`plone:contributing/index`.


## Prerequisites

Prepare your system by installing {ref}`plone:plone-prerequisites-label`.


## 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.

```shell
make install
```

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

```shell
make help
```


## Start Plone

```shell
make start
```


## 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.

```shell
.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.

````markdown
```{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.

```shell
make docs-livehtml
```

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


## Documentation checks

Run a link checker on documentation.

```shell
make docs-linkcheckbroken
```

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

```shell
make docs-vale
```


## Conventions

```{toctree}
:maxdepth: 2

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](https://black.readthedocs.io/en/stable/index.html).

```shell
make check
```

Use the following command to run tests.

```shell
make test
```