plone.org
-
-
- plone.org
-
The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.
- """, + "extra_footer": """The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.
""", } # Theme options are theme-specific and customize the look and feel of a theme diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 5654a396d4..1c0c9ac617 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -1,13 +1,24 @@ --- 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" + "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" --- -# Contributing to `plone.restapi` +# Contribute to `plone.restapi` + +This section describes how to contribute to the `plone.restapi` project. +It extends {doc}`plone:contributing/index`. + + +## Pre-requisites + +Prepare your system by installing {ref}`plone:plone-pre-requisites-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. @@ -16,21 +27,27 @@ To install this package, its dependencies, and its documentation, code formattin make ``` -## Generating documentation examples +To see all the Makefile targets and help, use the following command. + +```shell +make help +``` + + +## Generate documentation examples -This documentation includes examples of requests and responses (http, curl, httpie, and python-requests). +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 +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/`. +The above command also generates the request and the response files in `tests/http-examples/`. +Include them in the documentation using MyST syntax. -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 @@ -40,31 +57,14 @@ Include them in the documentation using MyST syntax: ``` ```` -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 +Build the documentation locally to test the rendering. -`docs-livehtml` -: Rebuild Sphinx documentation on changes, with live-reload in the browser - -`docs-vale` -: Run spell, grammar, and style checks +```shell +make docs-html +``` -`docs` -: Build Docs +Add and commit the generated files in `src/plone/restapi/tests/http-examples/`. -Make sure you add and commit the generated files in `http-examples`. ## Conventions @@ -76,18 +76,18 @@ 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. +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 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. +Use the following command to run tests. ```shell make test ``` + diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 9d440d0eb9..0000000000 --- a/netlify.toml +++ /dev/null @@ -1,5 +0,0 @@ -[build.environment] - PYTHON_VERSION = "3.8" - -[build] - ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ./docs/" diff --git a/news/1798.documentation b/news/1798.documentation new file mode 100644 index 0000000000..b56db95533 --- /dev/null +++ b/news/1798.documentation @@ -0,0 +1 @@ +Update contributing docs for Plone 6, and switch from Netlify to Read the Docs for pull request previews. @stevepiercy diff --git a/plone-6.0.x-python3.8.cfg b/plone-6.0.x-python3.8.cfg new file mode 100644 index 0000000000..9fca1a2f0e --- /dev/null +++ b/plone-6.0.x-python3.8.cfg @@ -0,0 +1,17 @@ +[buildout] +extends = + https://dist.plone.org/release/6.0.11.1/versions.cfg + base.cfg + +[instance] +recipe = plone.recipe.zope2instance +zodb-temporary-storage = off + +[versions] +pygments = 2.14.0 +plone.app.linkintegrity = 4.0.3 +robotframework-browser = 17.5.2 +robotframework-assertion-engine = 2.0.0 +robotframework-debuglibrary = 2.3.0 +robotframework-pythonlibcore = 4.2.0 +grpcio-tools = 1.59.0 diff --git a/plone-6.0.x.cfg b/plone-6.0.x.cfg index 5c418ddfe0..5172c9ddaf 100644 --- a/plone-6.0.x.cfg +++ b/plone-6.0.x.cfg @@ -13,6 +13,8 @@ recipe = plone.recipe.zope2instance zodb-temporary-storage = off [versions] +# Override pin from Zope. https://github.com/zopefoundation/Zope/issues/1220 +docutils = 0.21.2 pygments = 2.14.0 plone.app.linkintegrity = 4.0.3 robotframework-browser = 17.5.2 diff --git a/plone-6.1.x.cfg b/plone-6.1.x.cfg index 2ac1f2b5af..54716fa951 100644 --- a/plone-6.1.x.cfg +++ b/plone-6.1.x.cfg @@ -12,4 +12,6 @@ parts = recipe = plone.recipe.zope2instance zodb-temporary-storage = off -[versions] \ No newline at end of file +[versions] +# Override pin from Zope. https://github.com/zopefoundation/Zope/issues/1220 +docutils = 0.21.2
-