---
myst:
html_meta:
"description": "Contributing to plone.restapi"
"property=og:description": "Contributing to plone.restapi"
"property=og:title": "Contributing to plone.restapi"
"keywords": "Plone, plone.restapi, REST, API, Contributing, documentation"
---
# 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.
```shell
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
```shell
./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`.
## Conventions
```{toctree}
:maxdepth: 2
conventions
```
## Code formatting and testing
To ensure consistent code formatting, we use [Black](https://black.readthedocs.io/en/stable/index.html).
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.
```shell
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.
```shell
make test
```