Another revision of uv-managed branch (#2074)

* More uv managed revisions
- The instructions for installation from PyPI have only two options, Cookieplone and Buildout, not the three options from the include. The attempt to avoid DRY with an include won't work here.

* - DRY for complete the add-on installation

* "mxdev" isn't an inline literal

* "mxdev" isn't an inline literal

* tighten up spacing

* grammar

* Increasing specificity

* Make URL clickable

* Add an introductory paragraph to the empty subheading

* - Link to sections in add-ons documentation
- spelling of mxdev and pip
- Oxford comma

* Fix Vale errors

* Fix Vale errors

* Remove unnecessary section subheading

* Promote uv as the first package manager, and combine its first two sentences.

* MyST markup, grammar, link to the pip interface for uv

* Update docs/conceptual-guides/package-management.md

* Update docs/admin-guide/override-core.md

Co-authored-by: David Glick <david@glicksoftware.com>

---------

Co-authored-by: David Glick <david@glicksoftware.com>

Author: stevepiercy

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/admin-guide/add-ons.md

@@ -98,17 +98,39 @@ You can control which version of an add-on to install through "version pinning."
 
 ### Install the add-on
 
-```{include} /_inc/_build-and-restart.md
+If the backend is running, stop it with {kbd}`ctrl-c`.
+
+To actually download and install the new add-on, run the following command.
+
+`````{tab-set}
+````{tab-item} Cookieplone
+:sync: cookieplone
+
+```shell
+make backend-build
+```
+````
+
+````{tab-item} Buildout
+:sync: buildout
+
+```shell
+bin/buildout -N
 ```
+````
+`````
+
+Next, restart the backend.
 
-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.
+```{seealso}
+{doc}`run-plone`
+```
 
-Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
+```{include} /_inc/_add-on-complete-install.md
+```
 
-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-an-add-on-from-source-label)=
 
 ## Install an add-on from source
 
@@ -190,7 +212,7 @@ extras=test
 
 ```{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`.
+For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`.
 ```
 ````
 
@@ -243,10 +265,5 @@ This way you always get the version that's currently available in the source con
 ```{include} /_inc/_build-and-restart.md
 ```
 
-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.
+```{include} /_inc/_add-on-complete-install.md
+```

docs/admin-guide/override-core.md

@@ -16,11 +16,11 @@ Sometimes you will need to override one or more package versions to fix a bug.
 
 ## Override the version of a core Plone package
 
-The Python packages which are dependencies of Plone are pinned to specific versions at the time a Plone release is created.
+Plone's Python package dependencies are pinned to specific versions at the time a Plone release is created.
 This section describes how to override the version of one of these packages, in case you need a newer one.
 
 ```{caution}
-By doing this, you are intentionally using a combination of package versions that has not been tested by the Plone development team.
+When you override package versions, the combination of packages isn't tested by the Plone development team.
 Use at your own risk!
 ```
 
@@ -37,11 +37,10 @@ For projects created with Cookieplone, select the tab labeled:
 ```
 
 `````{tab-set}
-
 ````{tab-item} uv
 :sync: uv
 
-Edit `constraint-dependencies` in the file {file}`pyproject.toml`.
+In the file {file}`pyproject.toml`, under the table `[tool.uv]`, edit `constraint-dependencies`.
 This example uses `plone.api`.
 
 ```
@@ -50,13 +49,12 @@ constraint-dependencies = [
     "plone.api==2.0.0a3",
 ]
 ```
-
 ````
 
 ````{tab-item} pip
 :sync: pip
 
-Add a version override to the file {file}`backend/mx.ini`.
+In the file {file}`backend/mx.ini`, under the `[settings]` section, add `version-overrides` setting.
 This example uses `plone.api`.
 
 ```
@@ -67,9 +65,8 @@ version-overrides =
 
 ```{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`.
+For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`.
 ```
-
 ````
 
 ````{tab-item} Buildout
@@ -98,11 +95,9 @@ plone.api = 2.0.0a3
 ```
 
 ```{note}
-The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`.
+The version pins specified in the `[versions]` section will take precedence over the pins inherited from https://dist.plone.org/release/6-latest/versions.cfg.
 ```
-
 ````
-
 `````
 
 ### Install the package
@@ -128,7 +123,6 @@ For projects created with Cookieplone, select the tab labeled:
 ```
 
 `````{tab-set}
-
 ````{tab-item} uv
 :sync: uv
 
@@ -146,7 +140,6 @@ Add the local directory to your uv project as an editable package.
 cd backend
 uv add --editable ../plone.restapi
 ```
-
 ````
 
 ````{tab-item} pip
@@ -164,9 +157,8 @@ extras = test
 
 ```{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`.
+For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`.
 ```
-
 ````
 
 ````{tab-item} Buildout
@@ -207,9 +199,7 @@ Setting an empty version ensures that the copy of `plone.restapi` from source co
 ```{seealso}
 This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
 ```
-
 ````
-
 `````
 
 ### Install the package

docs/conceptual-guides/package-management.md

@@ -11,7 +11,7 @@ myst:
 
 Plone 6 consists of a collection of Python and Node.js packages.
 Over the decades of its existence, Plone has used several package management tools, sometimes multiple tools at one time.
-Each one has its strengths and weaknesses for performing specific tasks, such as installation, conflict resolution, updates and upgrades, and working with virtual environments and across platforms.
+Each one has its strengths and weaknesses for performing specific tasks, such as installation, conflict resolution, updates, upgrades, and working with virtual environments and across platforms.
 
 With Volto as the default frontend in Plone 6, first npm, then pnpm, was brought into the mix as a package manager for its Node.js packages.
 
@@ -26,6 +26,21 @@ Python itself has a complex and convoluted history with package management, as [
 
 ## Manage backend Python packages
 
+uv, pip with mxdev, and buildout are supported tools to manage the Python packages in the Plone backend.
+The following sections explain each of these tools in more detail.
+
+
+### uv
+
+{term}`uv` is a package manager which is popular for its speed, its ability to manage the installation of Python itself, and its ability to consistently reproduce installed packages using a {file}`uv.lock` file.
+
+When a project is fully managed using uv, it is configured in its {file}`pyproject.toml` file, and its packages are installed using `uv sync`.
+
+uv also has a [pip interface](https://docs.astral.sh/uv/pip/), and installs packages into a virtual environment via the command `uv pip install`.
+
+If you create a Plone project using Cookieplone, it creates a backend managed by uv.
+
+
 ### pip
 
 By convention in the Python community, {term}`pip` is commonly used to install Python packages.
@@ -49,37 +64,26 @@ As a best practice, pip should always be used inside a specific Python {term}`vi
 
 During development, it is sometimes necessary to override the Plone version constraints.
 This makes it possible to:
-- install a newer version of a core Plone package that was released with a bugfix
-- install an unreleased core Plone package from a source control system
+- {ref}`install a newer version of a core Plone package that was released to PyPI <install-an-add-on-from-pypi-label>` with a bugfix
+- {ref}`install an unreleased core Plone package from a source control system <install-an-add-on-from-source-label>`
 
-Unfortunately pip does not allow overriding constraints this way.
+pip does not allow overriding constraints this way.
 {term}`mxdev` solves this issue.
 
-`mxdev` resolves Plone constraints according to your needs for pinning versions or source checkouts.
+mxdev resolves Plone constraints according to your needs for pinning versions or source checkouts.
 It reads its configuration file {file}`mx.ini`, and your {file}`requirements.txt` and {file}`constraints.txt` files.
 Then it fetches the requirements and constraints of Plone.
 Finally, it writes new combined requirements in {file}`requirements-mxdev.txt` and new constraints in {file}`constraints-mxdev.txt`.
 Together these two files contain the combined requirements and constraints, but modified according to the configuration in {file}`mx.ini`.
 The generated files indicate from where the constraints were fetched, and comments are added when a modification was necessary.
 
-`mxdev` does not run `pip` or install packages.
+mxdev does not run pip or install packages.
 You or your development tools, such as GNU Make, must perform that step.
 
 ```{seealso}
 {doc}`/admin-guide/add-ons`
 ```
 
-### uv
-
-More recently, {term}`uv` has become popular as a way to install Python packages.
-This package manager is popular for its speed, its ability to manage the installation of Python itself, and its ability to consistently reproduce installed packages using a {file}`uv.lock` file.
-
-When a project is fully managed using uv, it is configured in `pyproject.toml` and the packages are installed using `uv sync`.
-
-uv also has a backwards-compatible mode which works more like pip, and installs packages into a virtual environment via the command `uv pip install`.
-
-If you create a Plone project using Cookieplone, it creates a backend managed by uv.
-
 ### buildout
 
 {term}`Buildout` is a tool for installing Python packages that has been used in the Plone community since about 2007, and is still preferred by some members of the community.
@@ -89,9 +93,8 @@ It not only installs packages, but can set up other things using an extensible s
 Buildout does not install Python packages into a virtual environment.
 Instead, it creates scripts that add the necessary packages to `sys.path` before running the script target.
 
-## Manage frontend Node.js packages
 
-### pnpm
+## Manage frontend Node.js packages
 
 Plone uses {term}`pnpm` to install Node.js packages.
 

styles/config/vocabularies/Plone/accept.txt

@@ -10,24 +10,28 @@ backport(ed|ing)
 Barceloneta
 [Bb]oolean
 bugfix
-buildout
+[Bb]uildout
 cacheable
 Classic UI
+CMSs
 CMSUI
 CommonJS
 Cookieplone
 doctest
 ETags?
+extranets
 [Ff]avicon
 folderish
 fieldset
 getter
+interoperate
 JavaScript
 [Jj]enkins
 jQuery
 libxslt
 middleware
 Mockup
+mxdev
 namespaces?
 npm
 nvm
@@ -39,6 +43,7 @@ PLIP(s)
 Plone
 plonecli
 pluggab(le|ility)
+pnpm
 [Pp]ortlets?
 prerendered
 programatically
@@ -67,4 +72,5 @@ Volto
 Vue
 webpack
 wireframe
+xkcd
 Zope