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