plone.api 2.2.1__tar.gz → 2.2.2__tar.gz

{plone_api-2.2.1 → plone_api-2.2.2}/CHANGES.rst

@@ -8,6 +8,16 @@ Changelog
 
 .. towncrier release notes start
 
+2.2.2 (2024-07-30)
+------------------
+
+Documentation:
+
+
+- Overhaul contributing documentation for Plone 6. @stevepiercy (#539)
+- Use correct syntax for `no-index` in documentation. @stevepiercy (#540)
+
+
 2.2.1 (2024-06-26)
 ------------------
 

plone_api-2.2.2/CONTRIBUTING.rst

@@ -0,0 +1 @@
+Please see [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).

{plone_api-2.2.1 → plone_api-2.2.2}/PKG-INFO

@@ -1,11 +1,14 @@
 Metadata-Version: 2.1
 Name: plone.api
-Version: 2.2.1
+Version: 2.2.2
 Summary: A Plone API.
 Home-page: https://github.com/plone/plone.api
 Author: Plone Foundation
 Author-email: plone-developers@lists.sourceforge.net
 License: GPL version 2
+Project-URL: Documentation, https://6.docs.plone.org/plone.api/index.html
+Project-URL: Changelog, https://github.com/plone/plone.api/blob/master/CHANGES.rst
+Project-URL: Issue Tracker, https://github.com/plone/plone.api/issues
 Keywords: plone api
 Platform: Any
 Classifier: Development Status :: 5 - Production/Stable
@@ -85,8 +88,7 @@ Recipes try to assume the user does not have extensive knowledge about Plone int
 
 
 Contributors
-    Please read the document [Process for Plone core's development](https://5.docs.plone.org/develop/coredev/docs/index.html).
-    Also consult the section about contribution in the [plone.api contributors documentation](https://5.docs.plone.org/develop/plone.api/docs/contribute/index.html).
+    Please read [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).
 
 Source Code
     at the [Plone code repository hosted at GitHub](https://github.com/plone/plone.api).
@@ -111,6 +113,16 @@ Changelog
 
 .. towncrier release notes start
 
+2.2.2 (2024-07-30)
+------------------
+
+Documentation:
+
+
+- Overhaul contributing documentation for Plone 6. @stevepiercy (#539)
+- Use correct syntax for `no-index` in documentation. @stevepiercy (#540)
+
+
 2.2.1 (2024-06-26)
 ------------------
 

{plone_api-2.2.1 → plone_api-2.2.2}/README.md

@@ -29,8 +29,7 @@ Recipes try to assume the user does not have extensive knowledge about Plone int
 
 
 Contributors
-    Please read the document [Process for Plone core's development](https://5.docs.plone.org/develop/coredev/docs/index.html).
-    Also consult the section about contribution in the [plone.api contributors documentation](https://5.docs.plone.org/develop/plone.api/docs/contribute/index.html).
+    Please read [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).
 
 Source Code
     at the [Plone code repository hosted at GitHub](https://github.com/plone/plone.api).

plone_api-2.2.2/docs/contribute.md

@@ -0,0 +1,244 @@
+---
+myst:
+  html_meta:
+    "description": "Contribute to plone.api"
+    "property=og:description": "Contribute to plone.api"
+    "property=og:title": "Contribute to plone.api"
+    "keywords": "plone.api, contribute, Plone, API, development"
+---
+
+# Contribute to `plone.api`
+
+This section describes how to contribute to the `plone.api` project.
+It extends {doc}`plone:contributing/index`.
+
+
+## Pre-requisites
+
+Prepare your system by installing pre-requisites.
+
+
+### System libraries
+
+You need to install system libraries, as described in {ref}`plone:plone-pre-requisites-label`, with the exception of GNU make.
+
+
+### tox
+
+[tox](https://tox.wiki/en/stable/index.html) automates and standardizes testing in Python.
+Install tox into your Python user space with the following command.
+
+```shell
+python -m pip install --user tox
+```
+
+### pre-commit
+
+`plone.api` uses [pre-commit](https://pre-commit.com/) to automate code quality checks before every commit.
+
+Install pre-commit either with your system package manager.
+Alternatively you can install pre-commit into your Python user.
+
+```shell
+python -m pip install --user pre-commit
+```
+
+Once installed, set up the git hook scripts to run on every commit.
+
+```shell
+pre-commit install
+```
+
+
+## Create development environment
+
+After satisfying the pre-requisites, you are ready to create your development environment.
+`plone.api` uses `tox` as a wrapper around `coredev.buildout` to simplify development, whereas Plone core uses `coredev.buildout` directly.
+
+Start by changing your working directory to your project folder, and download the latest `plone.api` source code.
+
+```shell
+cd <your_project_folder>
+git clone https://github.com/plone/plone.api.git
+```
+
+Next go into the newly created directory, and build your environment.
+
+```shell
+cd plone.api
+tox
+```
+
+Go make some tea while `tox` runs all tasks listed by issuing the command `tox -l`.
+
+Open `tox.ini` in your code editor to see all configured commands and what they do.
+Some helpful `tox` commands are shown below.
+
+```shell
+tox -e py39-plone-60  # run all tests for Python 3.9 and Plone 6
+tox -e plone6docs     # build documentation
+tox -e livehtml       # build, serve, and reload changes to documentation
+tox -l                # list all tox environments
+```
+
+
+(git-workflow)=
+
+## git
+
+Use the following git branches when contributing to `plone.api`.
+
+feature branches
+:   All development for a new feature or bug fix must be done on a new branch.
+
+`master`
+:   Pull requests should be made from a feature branch against the `master` branch.
+    When features and bug fixes are complete and approved, they are merged into the `master` branch.
+
+```{seealso}
+{ref}`plone:contributing-core-work-with-git-label`
+```
+
+
+## Continuous integration
+
+`plone.api` uses GitHub workflows for continuous integration.
+On every push to the `master` branch, GitHub runs its workflows for all tests and code quality checks.
+GitHub workflows are configured in the directory `.github/workflows` at the root of this package.
+
+
+## Documentation
+
+For every feature change or addition to `plone.api`, you must add documentation of it.
+`plone.api` uses [MyST](https://myst-parser.readthedocs.io/en/latest/) for documentation syntax.
+
+```{seealso}
+{doc}`plone:contributing/documentation/index`
+```
+
+After adding or modifying documentation, you can build the documentation with the following command.
+
+```shell
+tox -e plone6docs
+```
+
+Alternatively, you can automatically reload changes to the documentation as you edit it in a web browser.
+
+```shell
+tox -e livehtml
+```
+
+The [`plone.api` documentation](https://6.docs.plone.org/plone.api) is automatically generated from the documentation source files when its submodule is updated in the [main Plone `documentation` repository](https://github.com/plone/documentation/).
+
+
+## Add a function to an existing module
+
+This section describes how to add a new function `foo` to `plone.api`.
+
+The function would go in the module `plone.api.content`, located in the file {file}`src/plone/api/content.py`.
+
+% invisible-code-block: python
+%
+% from plone.api.validation import at_least_one_of
+% from plone.api.validation import mutually_exclusive_parameters
+
+```python
+@mutually_exclusive_parameters('path', 'UID')
+@at_least_one_of('path', 'UID')
+def foo(path=None, UID=None):
+    """Do foo.
+
+    :param path: Path to the object we want to get,
+        relative to the portal root.
+    :type path: string
+
+    :param UID: UID of the object we want to get.
+    :type UID: string
+
+    :returns: String
+    :raises:
+        :class:`~plone.api.exc.MissingParameterError`,
+        :class:`~plone.api.exc.InvalidParameterError`
+    :Example: :ref:`content-foo-example`
+    """
+    return "foo"
+```
+
+% invisible-code-block: python
+%
+% bar = foo('/plone/blog')
+% self.assertEqual(bar,"foo")
+%
+% from plone.api.exc import InvalidParameterError
+% self.assertRaises(
+%     InvalidParameterError,
+%     lambda: foo("/plone/blog", "abcd001")
+% )
+
+Add documentation in {file}`docs/api/content.md`.
+Narrative documentation should describe what your function does.
+
+You should also write some tests in code blocks.
+`TestCase` methods, such as `self.assertEqual()`, are available in `doctests`.
+See [unittest.TestCase assert methods](https://docs.python.org/3/library/unittest.html#unittest.TestCase.debug) for all available methods.
+The file is linked in `/src/plone/api/tests/doctests/`, which includes the doctests in `plone.api`'s test setup.
+The package `manuel` allows you to write doctests as common Python code in code blocks.
+
+The following example shows narrative documentation and doctests.
+
+````markdown
+(content-foo-example)=
+
+## Get the foo of an object
+
+You can use the {meth}`api.content.foo` function to get the `foo` of an object.
+
+```python
+from plone import api
+blog_foo = api.content.foo(path="/plone/blog")
+```
+
+% invisible-code-block: python
+%
+% self.assertEqual(blog_foo,"foo")
+````
+
+Code blocks are rendered in documentation.
+
+````markdown
+```python
+from plone import api
+blog_foo = api.content.foo(path="/plone/blog")
+```
+````
+
+Invisible code blocks are not rendered in documentation and can be used for tests.
+
+```markdown
+% invisible-code-block: python
+%
+% self.assertEqual(blog_foo,"foo")
+```
+
+Invisible code blocks are also handy for enriching the namespace without cluttering the narrative documentation.
+
+```markdown
+% invisible-code-block: python
+%
+% portal = api.portal.get()
+% image = api.content.create(type='Image', id='image', container=portal)
+% blog = api.content.create(type='Link', id='blog', container=portal)
+```
+
+Functions and examples in documentation are mutually referenced.
+The function references the narrative documentation via the label `content-foo-example`.
+The narrative documentation references the API function documentation via `` {meth}`api.content.foo` ``.
+The documentation is rendered with a link from the API reference to the narrative documentation, which in turn links back to the API reference.
+
+
+## Resources
+
+-   {doc}`plone:index`
+-   [Source code](https://github.com/plone/plone.api)
+-   [Issue tracker](https://github.com/plone/plone.api/issues)
+-   [Code Coverage](https://coveralls.io/github/plone/plone.api)

{plone_api-2.2.1/src/plone/api/tests/doctests → plone_api-2.2.2/docs}/env.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-env)=

{plone_api-2.2.1/src/plone/api/tests/doctests → plone_api-2.2.2/docs}/group.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-groups)=

{plone_api-2.2.1 → plone_api-2.2.2}/docs/index.md

@@ -72,7 +72,7 @@ api/index
 ```{toctree}
 :maxdepth: 2
 
-contribute/index
+contribute
 ```
 
 ## Indices and tables

{plone_api-2.2.1/src/plone/api/tests/doctests → plone_api-2.2.2/docs}/portal.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-portal)=

{plone_api-2.2.1/src/plone/api/tests/doctests → plone_api-2.2.2/docs}/relation.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-relation)=

{plone_api-2.2.1 → plone_api-2.2.2}/docs/user.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-users)=

{plone_api-2.2.1 → plone_api-2.2.2}/setup.py

@@ -3,7 +3,7 @@ from setuptools import find_packages
 from setuptools import setup
 
 
-version = "2.2.1"
+version = "2.2.2"
 
 long_description = (
     f"{Path('README.md').read_text()}\n"
@@ -80,4 +80,9 @@ setup(
         "Programming Language :: Python :: 3.11",
     ],
     platforms="Any",
+    project_urls={
+        "Documentation": "https://6.docs.plone.org/plone.api/index.html",
+        "Changelog": "https://github.com/plone/plone.api/blob/master/CHANGES.rst",
+        "Issue Tracker": "https://github.com/plone/plone.api/issues",
+    },
 )

{plone_api-2.2.1/docs → plone_api-2.2.2/src/plone/api/tests/doctests}/env.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-env)=

{plone_api-2.2.1/docs → plone_api-2.2.2/src/plone/api/tests/doctests}/group.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-groups)=

{plone_api-2.2.1/docs → plone_api-2.2.2/src/plone/api/tests/doctests}/portal.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-portal)=

{plone_api-2.2.1/docs → plone_api-2.2.2/src/plone/api/tests/doctests}/relation.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-relation)=

{plone_api-2.2.1 → plone_api-2.2.2}/src/plone/api/tests/doctests/user.md

@@ -9,7 +9,7 @@ myst:
 
 ```{eval-rst}
 .. module:: plone
-    :noindex:
+    :no-index:
 ```
 
 (chapter-users)=

{plone_api-2.2.1 → plone_api-2.2.2}/src/plone.api.egg-info/PKG-INFO

@@ -1,11 +1,14 @@
 Metadata-Version: 2.1
 Name: plone.api
-Version: 2.2.1
+Version: 2.2.2
 Summary: A Plone API.
 Home-page: https://github.com/plone/plone.api
 Author: Plone Foundation
 Author-email: plone-developers@lists.sourceforge.net
 License: GPL version 2
+Project-URL: Documentation, https://6.docs.plone.org/plone.api/index.html
+Project-URL: Changelog, https://github.com/plone/plone.api/blob/master/CHANGES.rst
+Project-URL: Issue Tracker, https://github.com/plone/plone.api/issues
 Keywords: plone api
 Platform: Any
 Classifier: Development Status :: 5 - Production/Stable
@@ -85,8 +88,7 @@ Recipes try to assume the user does not have extensive knowledge about Plone int
 
 
 Contributors
-    Please read the document [Process for Plone core's development](https://5.docs.plone.org/develop/coredev/docs/index.html).
-    Also consult the section about contribution in the [plone.api contributors documentation](https://5.docs.plone.org/develop/plone.api/docs/contribute/index.html).
+    Please read [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).
 
 Source Code
     at the [Plone code repository hosted at GitHub](https://github.com/plone/plone.api).
@@ -111,6 +113,16 @@ Changelog
 
 .. towncrier release notes start
 
+2.2.2 (2024-07-30)
+------------------
+
+Documentation:
+
+
+- Overhaul contributing documentation for Plone 6. @stevepiercy (#539)
+- Use correct syntax for `no-index` in documentation. @stevepiercy (#540)
+
+
 2.2.1 (2024-06-26)
 ------------------
 

{plone_api-2.2.1 → plone_api-2.2.2}/src/plone.api.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ setup.py
 tox.ini
 docs/about.md
 docs/content.md
+docs/contribute.md
 docs/env.md
 docs/group.md
 docs/index.md

{plone_api-2.2.1 → plone_api-2.2.2}/tox.ini

@@ -257,17 +257,15 @@ allowlist_externals =
 [testenv:plone6docs]
 # New docs with sphinx-book-theme
 # See [testenv:docs] for classic documentation
-basepython = python3.9
+basepython = python3.11
 skip_install = False
-usedevelop = True
+package = editable
 allowlist_externals =
     mkdir
 extras =
     tests
-
 deps =
     -r requirements-docs.txt
-
 commands =
     python -VV
     mkdir -p {toxinidir}/_build/plone6docs
@@ -294,9 +292,9 @@ whitelist_externals =
     mkdir
 
 [testenv:linkcheck]
-basepython = python
+basepython = python3.11
 skip_install = False
-usedevelop = True
+package = editable
 allowlist_externals =
     mkdir
 extras =
@@ -308,6 +306,21 @@ commands =
     mkdir -p {toxinidir}/_build/plone6docs
     sphinx-build -b linkcheck -d _build/plone6docs/doctrees docs _build/plone6docs/linkcheck
 
+[testenv:livehtml]
+basepython = python3.11
+skip_install = False
+package = editable
+allowlist_externals =
+    mkdir
+extras =
+    {[testenv:plone6docs]extras}
+deps =
+    {[testenv:plone6docs]deps}
+commands =
+    python -VV
+    mkdir -p {toxinidir}/_build/plone6docs
+    sphinx-autobuild -b html -d _build/plone6docs/doctrees docs _build/plone6docs/html
+
 ##
 # Add extra configuration options in .meta.toml:
 #  [tox]

plone_api-2.2.1/CONTRIBUTING.rst

@@ -1 +0,0 @@
-Please see https://5.docs.plone.org/develop/coredev/docs/guidelines.html