Document distributions in the 6.1 upgrade guide. (#1733)

* Document distributions in the 6.1 upgrade guide. See plone/Products.CMFPlone#3854 * Review of Distributions documentation * Align term definition with upgrade guide docs, avoiding circular reference. * Fix admonition syntax * Add link to repo * Enhance screenshot with card syntax * plone.exportimport is not for upgrading Plone. If you need an export/import for upgrading Plone you would still use collective.exportimport. Upgrading is not a use case that plone.exportimport covers. * Here we do not start a new project, I just mean: start Plone. * These are not 'frontend distributions'. * Creating a 6.1 CMFPlone site differs from 6.0, that is the main point here. * Don't mention installing add-ons here, activating is enough. Sure, the Python package of an add-on must be installed before you can activate it, but the same is true for a distribution. The plone.classicui distribution has basically the same Python package dependencies as CMFPlone, although it activates a few extra ones automatically if they are available (say plone.app.caching). * reorganize distribution docs * Apply suggestions from code review * Update conceptual guide for distributions, where the significant changes are: - Use the actual package names of the built-in distributions - Move the comparison to other CMSs to the end of the page, putting Plone-only content first. * Create an entry in `index.md` to include a new `developer-guide/index.md` and the new `developer-guide/create-a-distribution.md` * Update glossary reference to other distribution material * Add cross-reference * Add JSON Schema to Glossary * Tidy up create-a-distribution.md. - Rewrite passive voice to active. - Enhance code blocks with `emphasize-lines`. - Use definition lists as appropriate for terms and inline literals. - Add links and terms where helpful. * Revert distribution names and enhance `ALLOWED_DISTRIBUTIONS` usage. * Tidy up add-site.md, mostly docs style guide stuff, and a rewording of the final admonition. Add plural `distributions` to Glossary. * Tidy up distributions section in upgrade-to-61.md * Update docs/backend/upgrading/version-specific-migration/upgrade-to-61.md Co-authored-by: David Glick <[email protected]> * Move add-site into Admin Guide. Move Admin Guide before Developer Guide in main navigation * Remove stray characters from bad merge * Resolve TODOs by moving file and adding link to new choose-user-interface. * Update glossary with Zope instance and cross-references to Zope itself. * Fix cross-references * Fix link * Ignore link to static images * Ignore searches on GitHub as it rate limits and times out. * Update docs/developer-guide/index.md Co-authored-by: David Glick <[email protected]> --------- Co-authored-by: Steve Piercy <[email protected]> Co-authored-by: Maik Derstappen <[email protected]> Co-authored-by: David Glick <[email protected]>
plone · Nov 5, 2024 · 16f3bb4 · 16f3bb4
1 parent 55c4483
commit 16f3bb4
Show file tree

Hide file tree

Showing 12 changed files with 584 additions and 9 deletions.
diff --git a/docs/admin-guide/add-site.md b/docs/admin-guide/add-site.md
@@ -0,0 +1,73 @@
+---
+myst:
+  html_meta:
+    "description": "How to add a Plone site to an existing Zope instance"
+    "property=og:description": "How to add a Plone site to an existing Zope instance"
+    "property=og:title": "Add a Plone site"
+    "keywords": "Plone 6, create, add, factory, distributions"
+---
+
+(add-a-plone-site-label)=
+
+# Add a Plone site
+
+This section explains how to add a Plone site to an existing Zope instance.
+It assumes that you have already {doc}`installed </install/index>` and started Plone.
+
+Some installation methods create a Plone site for you already.
+Follow these instructions if you used an installation method that did not do this, or if you need a second Plone site in the same instance for some reason.
+
+```{versionadded} Plone 6.1
+The user interface for creating a new Plone site was changed in Plone 6.1.
+You can access it the same way in Plone 6.0, but the appearance and options are different.
+```
+
+Visit the Plone backend in a web browser.
+Usually it is running at http://localhost:8080/.
+
+The launch screen prompts you to choose one of the available {term}`distributions` to create a new site.
+You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI.
+
+````{card}
+```{image} /backend/upgrading/version-specific-migration/images/distribution-chooser.png
+:alt: Launch screen for choosing a distribution
+:target: /_images/distribution-chooser.png
+```
++++
+_Launch screen for choosing a distribution_
+````
+
+Hover over your choice and click the {guilabel}`Create` button.
+
+Now complete the form with initial configuration for your site.
+You can configure the following settings.
+
+Path Identifier
+:   The ID of the site.
+    This ends up as part of the URL unless hidden by an upstream web server.
+
+Title
+:   The name of the site in the HTML `title` element.
+    This will be shown as part of the title of the browser tab on each page.
+
+Site Description
+:   A brief description that will be served in an HTML `meta` tag.
+
+Site Logo
+:   Upload an image as the main site logo.
+
+Language
+:   The main language of the site.
+
+Timezone
+:   The default timezone setting of the portal.
+
+Finally, click the {guilabel}`Submit` button.
+
+Have fun with your new Plone site!
+
+```{important}
+The launch screen for adding a site is hosted by the Plone backend server.
+Regardless of the frontend you select, you will be redirected to the backend's user interface after you create the site.
+If you select the Volto frontend, you can switch to it by changing the port number in the URL, usually `3000`, and visiting it at http://localhost:3000, for example.
+```
diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md
@@ -29,6 +29,7 @@ install-pip
 :maxdepth: 1
 
 run-plone
+add-site
 configure-zope
 add-ons
 override-core

diff --git a/docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png b/docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png
diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-61.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-61.md
@@ -136,3 +136,44 @@ If you have an existing Plone 5.2 or 6.0 site and you migrate to 6.1, then migra
 -   If the `plone.app.discussion` Python package is _not_ in your setup, but the site has existing comments (discussions), then the migration code stops with an error.
     Apparently you _were_ using comments in your site.
     Add the `plone.app.discussion` package to your dependencies, and run the migration again.
+
+
+## Distributions
+
+Plone 6.1 introduces the concept of a Plone {term}`distribution`.
+A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site.
+Now it is available in core Plone as the recommended way for {doc}`creating a new Plone site </admin-guide/add-site>`.
+
+```{seealso}
+For more information about distribution concepts, see {doc}`/conceptual-guides/distributions`.
+```
+
+Distributions are optional.
+If your project only uses the `Products.CMFPlone` Python package, you can still create a Plone site in the old way.
+Consider, however, that doing so you will have the following differences when compared to using distributions.
+
+-   The configuration form is simpler and shorter.
+-   The created site has no content, and therefore no {guilabel}`News` or {guilabel}`Events` folders.
+-   You must activate add-ons through the {guilabel}`Add-ons` control panel.
+
+There are a few things you should consider when upgrading a project to, or making an add-on compatible with, Plone 6.1.
+
+-   In general, you don't need to change anything.
+    Your existing site will keep working.
+    But adding a new site may change in the ways described earlier.
+-   Do you want to use the `Products.CMFPlone` package (no distributions), either `plone.volto` or `plone.classicui` (one distribution), or `Plone` (two distributions)?
+-   If your site uses Volto for the frontend, you will already have `plone.volto` as a dependency.
+    This can stay the same.
+-   If your site depends on the `Products.CMFPlone` package without the `Plone` or `plone.volto` packages, then the frontend is Classic UI.
+    This can stay the same, but you may want to depend on `plone.classicui`.
+    With that package you can still create a new site and have the same content as before.
+-   If your site uses the `Plone` package, you will have the two new distributions available.
+    This is fine.
+    If you know you only need `plone.volto` or only need `plone.classicui`, you can switch to only one or the other.
+    You can also limit the options for selecting a distribution by setting the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options.
+    Set `ALLOWED_DISTRIBUTIONS=default` for the distribution targeting the Volto frontend (`plone.volto`).
+    Set `ALLOWED_DISTRIBUTIONS=classic` for the distribution with the Classic UI frontend (`plone.classicui`).
+-   If you switch from `Plone` to `plone.volto` or `plone.classicui`, you might want to install extra core add-ons, for example `plone.app.upgrade` or `plone.app.caching`.
+-   If your add-on is only for Volto, you might want to add `plone.volto` as a dependency.
+-   If your add-on is only for Classic UI, you might want to add `plone.classicui` as a dependency.
+    Note though that `plone.classicui` is not available for Plone 6.0.
diff --git a/docs/conceptual-guides/distributions.md b/docs/conceptual-guides/distributions.md
@@ -0,0 +1,89 @@
+---
+myst:
+  html_meta:
+    "description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
+    "property=og:description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
+    "property=og:title": "Plone distributions"
+    "keywords": "Plone 6, distribution, plone.distribution"
+---
+
+(plone-distributions-label)=
+
+# Plone distributions
+
+```{versionadded} Plone 6.1
+```
+
+A Plone {term}`distribution` is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations.
+It is a convenient way to get a specific type of website up and running quickly, as the distribution includes everything needed to run that type of site.
+
+```{seealso}
+To create your own distribution, see {doc}`/developer-guide/create-a-distribution`.
+```
+
+
+## Built-in distributions
+
+Plone comes with two built-in distributions, which correspond to the two Plone user interfaces.
+
+[`plone.volto`](https://github.com/plone/plone.volto)
+:   Create a Plone site with the Volto frontend.
+
+[`plone.classicui`](https://github.com/plone/plone.classicui) 
+:   Create a Plone site with the Classic UI frontend.
+
+
+## Third-party distributions
+
+You can create your own distributions to suit your needs.
+
+```{seealso}
+For a how-to guide, see {doc}`/developer-guide/create-a-distribution`.
+```
+
+For example, a Plone consulting agency can create a distribution demonstrating its favorite setup for Plone.
+This would contain the add-ons that they usually add in each project, including example content.
+With this, the agency can create a fully configured Plone site filled with content for a potential client.
+
+Alternatively, an agency or implementer can create a distribution for specific project.
+This could create a site with all add-ons activated and configured for this project, including example content, and optionally users and groups.
+During the development phase of a new project, all developers would use this to create a fresh site locally so that everyone has the same configuration and content.
+
+Custom Plone distributions can be distributions for use by others.
+Examples of third-party Plone distributions include:
+
+- [SENAITE](https://www.senaite.com)
+- [Quaive](https://quaive.com/)
+- [Portal Modelo](https://www.interlegis.leg.br/produtos-servicos/portal-modelo/)
+- [Portal Padrão](https://identidade-digital-de-governo-plone.readthedocs.io/en/latest/)
+
+
+## Related packages
+
+The implementation of distributions in the Plone codebase is found in the following Python packages.
+
+-   [`plone.distribution`](https://github.com/plone/plone.distribution) provides the framework for defining distributions.
+-   [`plone.exportimport`](https://github.com/plone/plone.exportimport) imports and exports content, users, and other objects between Plone sites.
+    `plone.distribution` uses it.
+-   [`plone.volto`](https://github.com/plone/plone.volto) is the distribution to create a Plone site with the Volto frontend.
+-   [`plone.classicui`](https://github.com/plone/plone.classicui) is the distribution to create a Plone site with the Classic UI frontend.
+
+```{note}
+For Plone 7, the [Plone roadmap](https://plone.org/why-plone/roadmap) guides development toward a clearer separation between the Classic UI frontend and the core `Products.CMFPlone` backend.
+This means that in Plone 7, `Products.CMFPlone` will have less code and pull in fewer dependencies, whereas `plone.classicui` may have more code and pull in more dependencies.
+This is the direction in which the backend is heading, and the introduction of the `plone.classicui` distribution package is an important step along this path.
+```
+
+## Comparison with other CMSs
+
+Drupal
+:   Drupal has distributions for blogs, e-commerce sites, and intranet portals.
+
+WordPress
+:   WordPress has a similar concept in the form of "WordPress Multisite," which allows users to run multiple websites from a single installation of WordPress.
+
+Joomla
+:   Joomla has a similar concept in the form of "Joomla Templates," which are pre-designed templates for Joomla websites.
+
+TYPO3
+:   TYPO3 has a similar concept in the form of "TYPO3 Distributions," which are pre-configured installations of TYPO3 for specific types of websites.
diff --git a/docs/conceptual-guides/index.md b/docs/conceptual-guides/index.md
@@ -16,6 +16,7 @@ This part of the documentation provides explanation of concepts to deepen and br
 :maxdepth: 2
 
 choose-user-interface
+distributions
 package-management
 make-build-backend-walk-through
 ```
diff --git a/docs/conceptual-guides/make-build-backend-walk-through.md b/docs/conceptual-guides/make-build-backend-walk-through.md
@@ -52,7 +52,7 @@ The command `make build-backend`:
 
 -   Returning to the target `build-dev`:
 
-    -   This generates the `mxdev` files as described above in {ref}`mxdev-usage-overview-label`.
+    -   This generates the `mxdev` files as described above in {ref}`manage-backend-python-packages-label`.
     -   Installs Plone core packages and add-ons from the files generated by `mxdev`.
 
 You can configure your Zope instance as described in the section {doc}`/admin-guide/configure-zope`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -82,15 +82,18 @@
     r"http://127.0.0.1",
     r"http://localhost",
     r"http://yoursite",
-    # Ignore file downloads
+    # Ignore static file downloads
     r"^/_static/",
+    r"^/_images/",
     # Ignore pages that require authentication
     r"https://github.com/orgs/plone/teams/",  # requires auth
     r"https://github.com/plone/documentation/issues/new/choose",  # requires auth
     r"https://github.com/plone/volto/issues/new/choose",  # requires auth
     r"https://opensource.org/",  # requires auth
     # Ignore github.com pages with anchors
     r"https://github.com/.*#.*",
+    # Ignore github.com searches
+    r"https://github.com/search",
     # Ignore other specific anchors
     r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main",  # plone.restapi
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",