Contributing to plone.restapi
We use GNU
make when developing
To install this package, its dependencies, and its documentation, code formatting, and testing tools, run the following command in the root of the project.
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
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
Include them in the documentation using MyST syntax:
.. http:example:: curl httpie python-requests
.. literalinclude:: ../../src/plone/restapi/tests/http-examples/search_fullobjects.resp
Build the documentation locally to test the rendering by running
Alternatively, you can use Makefile targets:
Clean current and legacy docs build directories, and Python virtual environment
Run linkcheck and show only broken links
Rebuild Sphinx documentation on changes, with live-reload in the browser
Run spell, grammar, and style checks
Make sure you add and commit the generated files in
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.
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.