Contributing to plone.restapi
#
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
.