Update docs to cover uv managed installations

docs/_inc/_add-on-complete-install.md

@@ -0,0 +1,7 @@
+In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
+
+Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
+
+Some add-ons have configuration options.
+To configure such add-ons, return to the {guilabel}`Site Setup` control panel.
+At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed.

docs/_inc/_build-and-restart.md

@@ -0,0 +1,35 @@
+If the backend is running, stop it with {kbd}`ctrl-c`.
+
+To actually download and install the package, run the following command.
+
+`````{tab-set}
+````{tab-item} uv
+:sync: uv
+
+```shell
+make backend-build
+```
+````
+
+````{tab-item} pip
+:sync: pip
+
+```shell
+make backend-build
+```
+````
+
+````{tab-item} Buildout
+:sync: buildout
+
+```shell
+bin/buildout -N
+```
+````
+`````
+
+Next, restart the backend.
+
+```{seealso}
+{doc}`run-plone`
+```

docs/admin-guide/add-ons.md

@@ -18,168 +18,206 @@ The Volto frontend has its own system of add-ons using Node.js packages.
 See {doc}`/volto/development/add-ons/index`.
 ```
 
+(install-an-add-on-from-pypi-label)=
 
-## Cookieplone
+## Install an add-on from PyPI
 
-Use the following instructions if you installed Plone with Cookieplone.
+This section describes how to install an add-on that is released on {term}`PyPI`.
 
 
-### Install an add-on
+(configure-add-on-installation-pypi-label)=
+
+### Configure add-on installation
+
+First, configure your project according to the instructions in the tabbed interface below.
+Select the tab according to the method you used to create your project.
+
+`````{tab-set}
+````{tab-item} Cookieplone
+:sync: cookieplone
 
 Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
 This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
 
 ```{code-block} toml
 :emphasize-lines: 6
 dependencies = [
-    "Products.CMFPlone==6.1.1",
+    "Products.CMFPlone==6.1.4",
     "plone.api",
     "plone.classicui",
     "plone.app.caching",
-    "collective.easyform==4.4.0",
+    "collective.easyform==4.5.1",
 ]
 ```
 
-```{tip}
-Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
-```
-
-Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
+To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
 
 ```yaml
 default_context:
     zcml_package_includes: project_title, collective.easyform
 ```
+````
 
-Stop the backend with {kbd}`ctrl-c`.
+````{tab-item} Buildout
+:sync: buildout
 
-To actually download and install the new add-on, run the following command.
+Update the file {file}`buildout.cfg`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
 
-```shell
-make backend-build
-```
+```cfg
+[buildout]
+extends =
+    https://dist.plone.org/release/6-latest/versions.cfg
 
-Now restart the backend.
+parts =
+    instance
 
-```{seealso}
-{doc}`run-plone`
+[instance]
+recipe = plone.recipe.zope2instance
+user = admin:admin
+http-address = 8080
+eggs =
+    Plone
+    collective.easyform
+
+[versions]
+collective.easyform = 4.5.1
 ```
+````
+`````
 
-In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
+```{tip}
+You can control which version of an add-on to install through "version pinning."
 
-Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
+-   Specify the add-on version to avoid its unintentional upgrade.
+-   Leave it off to always install the latest version.
+```
 
-Some add-ons have configuration options.
-To configure such add-ons, return to the {guilabel}`Site Setup` control panel.
-At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed.
 
+(install-the-add-on-pypi-label)=
 
-### Install an add-on from source
+### Install the add-on
 
-An add-on can be installed from a source control system such as GitHub.
+If the backend is running, stop it with {kbd}`ctrl-c`.
 
-Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
-This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+To actually download and install the new add-on, run the following command.
 
-```
-collective.easyform
-```
+`````{tab-set}
+````{tab-item} Cookieplone
+:sync: cookieplone
 
-```{note}
-When installing an add-on from source, it's best not to pin a version.
-This way you always get the version that's currently available in the source control system.
+```shell
+make backend-build
 ```
+````
 
-Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
+````{tab-item} Buildout
+:sync: buildout
 
-```yaml
-default_context:
-    zcml_package_includes: project_title, collective.easyform
+```shell
+bin/buildout -N
 ```
+````
+`````
 
-Finally, add the package's source to the file {file}`mx.ini`.
+Next, restart the backend.
 
-```cfg
-[collective.easyform]
-url=git@github.com:collective/collective.easyform.git
-branch=dev-branch-name
-extras=test
+```{seealso}
+{doc}`run-plone`
 ```
 
-```{seealso}
-The {file}`mx.ini` file configures a tool called {term}`mxdev`.
-See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information.
+```{include} /_inc/_add-on-complete-install.md
 ```
 
-Stop the backend with {kbd}`ctrl-c`.
 
-To actually download and install the new add-on, run the following command.
+(install-an-add-on-from-source-label)=
 
-```shell
-make backend-build
-```
+## Install an add-on from source
 
-Now restart the backend.
+This section describes how to install an unreleased add-on from a source control system, such as GitHub.
 
-```{seealso}
-{doc}`run-plone`
-```
 
-In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
-An upgrade step might need to be performed in the Plone control panel.
-Follow the upgrade information, if present.
-Else click the {guilabel}`Install` button to complete installation of the add-on.
+(configure-add-on-installation-source-label)=
 
+### Configure add-on installation
 
-## Buildout
+First, configure your project according to the instructions in the tabbed interface below.
+Select the tab according to your Python package manager.
 
-Use the following instructions if you installed Plone with Buildout.
+```{tip}
+For projects created with Cookieplone, select the tab labeled:
 
-### Install an add-on
+-   {guilabel}`pip` if your project has the file {file}`backend/mx.ini`
+-   {guilabel}`uv` if your project doesn't have this file
+```
 
-Update the file {file}`buildout.cfg`.
-This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+`````{tab-set}
+````{tab-item} uv
+:sync: uv
 
-```cfg
-[buildout]
-extends =
-    https://dist.plone.org/release/6-latest/versions.cfg
+Clone the repository into a local directory.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
 
-parts =
-    instance
+```shell
+git clone git@github.com:collective/collective.easyform.git
+```
 
-[instance]
-recipe = plone.recipe.zope2instance
-user = admin:admin
-http-address = 8080
-eggs =
-    Plone
-    collective.easyform
+Add the local directory to your uv project as an editable package.
 
-[versions]
-collective.easyform = 4.2.1
+```shell
+cd backend
+uv add --editable ../collective.easyform
 ```
 
-```{tip}
-Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
+To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
+
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
 ```
+````
 
-To actually download and install the new add-on, run the following command.
+````{tab-item} pip
+:sync: pip
 
-```shell
-bin/buildout
+Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
+This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+
+```{code-block} toml
+:emphasize-lines: 6
+dependencies = [
+    "Products.CMFPlone==6.1.4",
+    "plone.api",
+    "plone.classicui",
+    "plone.app.caching",
+    "collective.easyform",
+]
 ```
 
-Then restart your instance.
+To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
 
-```{seealso}
-{doc}`run-plone`
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
 ```
 
+Finally, add the package's source to the file {file}`mx.ini`.
+
+```cfg
+[collective.easyform]
+url=git@github.com:collective/collective.easyform.git
+branch=dev-branch-name
+extras=test
+```
 
-### Install an add-on from source
+```{seealso}
+The {file}`mx.ini` file configures a tool called {term}`mxdev`.
+For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`.
+```
+````
 
-You can install an add-on from a source control system such as GitHub.
+````{tab-item} Buildout
+:sync: buildout
 
 Update the file {file}`buildout.cfg`.
 This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
@@ -207,18 +245,25 @@ eggs =
 collective.easyform = git https://github.com/collective/collective.easyform.git
 ```
 
-To actually download and install the new add-on, run the following command.
+```{seealso}
+This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
+```
 
-```shell
-bin/buildout
+````
+`````
+
+```{tip}
+When installing an add-on from source, it's best not to pin a version.
+This way you always get the version that's currently available in the source control system.
 ```
 
-Then restart your instance.
 
-```{seealso}
-{doc}`run-plone`
+(install-the-add-on-source-label)=
+
+### Install the add-on
+
+```{include} /_inc/_build-and-restart.md
 ```
 
-```{seealso}
-This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
+```{include} /_inc/_add-on-complete-install.md
 ```