From c23fff9a7e48737c4ec7e04aad973b21dc53967b Mon Sep 17 00:00:00 2001 From: "Jens W. Klein" Date: Thu, 26 Sep 2024 12:45:11 +0200 Subject: [PATCH 01/10] see https://github.com/plone/documentation/issues/1683 --- .../contributing/core/package-dependencies.md | 221 ++++++++++++++---- 1 file changed, 172 insertions(+), 49 deletions(-) diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index de5c10c23..3ce4382f9 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -34,65 +34,188 @@ Nevertheless there is indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. -## Mental model +## Mental model -A base mental model for how Plone is organized in Plone 6, and is shown in the following diagram: +### Borders + +As a rough base mental model for how Plone is organized in Plone 6.1, there are two packages as dividing lines: + +1. `Products.CMFPlone` and all below defines the Plone core. Everything in here depends on the `plone.base`. +2. `plone.base` as the border to the Application Server and Content Management Framework and its dependencies ```{mermaid} block-beta - columns 1 - - Plone["Plone
the integraton of both distributions in one release"] - space + columns 4 + Plone["Plone
integraton of all in one release"]:4 Distributions - block:dist - plone.volto - plone.classicui - end - space - block:core - coreaddons["Core add-ons"] - coreapi["Core APIs"] - end - space - cmfplone["Products.CMFPlone"] - - space:2 - - block:layer - ploneapp["Most of plone.app.* namespace"] - otherlay["Various other packages"] - end - -space - - plonebase["plone.base"] - space - foundations["The Foundations"] - space:3 - block:foundationcomponents - ploneworld["Plone world"] - zopeeco["Zope ecosystem"] - zopecore["Zope core"] - libraries["Libraries"] - end - Plone --> Distributions - dist --> core - cmfplone --> layer - core --> cmfplone - layer --> plonebase - plonebase --> foundations - - style cmfplone fill:#ff0 - style plonebase fill:#ff0 + Upgrade + coreapis["Core APIs"] + coreaddons["Core add-ons"] + cmfplone["Products.CMFPlone"]:4 + ploneapp["Most of plone.app.* namespace"]:2 + otherlay["Various related packages"]:2 + plonebase["plone.base"]:4 + block:groupfoundation:4 + zopecore["Zope core/ ZCA"] + zopeeco["Zope ecosystem"] + cmfcore["CMFCore"] + ploneworld["Plone generic libraries"] + libraries["Other libraries"] + end + style cmfplone fill:#fff9e6 + style plonebase fill:#fff9e6 +``` + +### Main components + +Some explanation on the mental model + +- Foundation: + - `Zope` core and its dependencies is the application server, + - the Zope component architecture (ZCA) framework and + - some additional packages from the wider Zope ecosystem. + - then there are generic, standalone Plone libraries, + - plus various other Python libraries. +- `Products.CMFCore` provides on top of Zope very basic content management features we rely on. +- `plone.base` defines several interfaces as contracts for the component architecture we build on. + Additional it provides some base classes and utility functions we use often. + It also depends on `Products.CMFCore` and so `Zope`. + Additional it depends on generic functionality like `plone.dexterity`, `plone.behavior` and `plone.registry`. +- The space of plenty `plone.*`, `plone.app.*` and related libraries defines the core of Plone. +- On top of this core, depending on these packages, is `Products.CMFPlone` which is the package to depend on if the basic Plone core is referenced. +- On top of `Products.CMFPlone` + - are the core APIs like `plone.api` and `plone.restapi`, + - there is the distribution support `plone.distribution` and specific distributions, currently `plone.volto`, `plone.classicui`, + - are core addons like Working Copy Support (`plone.app.iterate`), discussion support (`plone.app.discussion`), ... + - is `plone.app.upgrade`, the package to upgrade between Plone version. +- The package `Plone` is the package to depend on if you want to depend on the whole Plone with everything. + This meta package without any code depends on all other packages. + It is what you want to install if you do not want to care about the details with all batteries included. + +### The space on top of CMFPlone + +Add-on developers and integrators are primary interacting with the dependencies on top of CMFPlone. +The following diagram visualizes this part. + +```{mermaid} +--- +config: + sankey: + showValues: false + width: 1600 + height: 800 + nodeAlignment: "right" +--- + +sankey-beta + + Plone,Distributions,100 + + Distributions,plone.volto,50 + Distributions,plone.classicui,30 + Distributions,other dist.,20 + + + + plone.volto,plone.distribution,10 + plone.volto,plone.restapi,20 + plone.volto,plone.api,20 + + Multlilingual,plone.api,20 + Commenting,plone.api,20 + Working Copies,plone.api, 20 + Caching,plone.api,20 + + plone.classicui,plone.distribution,15 + plone.classicui,plone.api,15 + other dist.,plone.distribution,4 + other dist.,plone.api,8 + other dist.,plone.restapi,8 + + + Plone,Core-Addons,80 + + Core-Addons,Multlilingual,20 + Core-Addons,Commenting,20 + Core-Addons,Working Copies,20 + Core-Addons,Caching,20 + + plone.distribution,Export/Import,15 + plone.distribution,plone.api,14 + plone.restapi,Core,20 + Export/Import,plone.api,8 + plone.restapi,plone.api,15 + Export/Import,plone.restapi,7 + Upgrade,Core,20 + plone.api,Core,160 + + Plone,Upgrade,20 ``` -As a rough model, there are two packages as dividing lines: +## A more detailed view on the architecture -1. `Products.CMFPlone` -2. `plone.base` +A more detailed view on the whole architecture is sketched here: +```{mermaid} +flowchart TB + subgraph Release["Release"] + Plone[["'Plone' Package"]] + end + subgraph subGraph1["Distributions"] + volto{{"plone.volto"}} + classicui{{"plone.classicui"}} + other{{"other ..."}} + end + subgraph Core-Addons["Core-Addons"] + multilingual("Multilingual") + iterate("Working Copies") + discussion("Commenting") + caching("Caching") + end + subgraph API["API"] + restapi("RestAPI") + ploneapi("API") + upgrade("Upgrade") + exportimport("Export/Import") + distribution["Distribution"] + end + subgraph subGraph4["The Inner Core"] + thecore((("Core-Features: plone.*, ..."))) + end + subgraph Core["Core"] + cmfplone["Products.CMFPlone"] + plonebase["plone.base"] + subGraph4 + end + subgraph Foundations["Foundations"] + zope["Zope/CMF/ZODB/..."] + supportlibs["Several Supporting Libraries"] + end + Plone == provides ==> volto + Plone -. provides .-> classicui & other & upgrade & multilingual & iterate & discussion & caching + volto -- installs --> restapi + volto == is a ==> distribution + classicui -. is a .-> distribution + other -. is a .-> distribution + distribution -- uses --> exportimport + distribution == depends on ==> ploneapi + restapi -- depends on --> ploneapi + cmfplone == depends on ==> thecore + thecore == depends on ==> plonebase + plonebase == depends on ==> zope + plonebase -- depends on --> supportlibs + zope -- depends on --> supportlibs + ploneapi == depends on ==> cmfplone + upgrade -- depends on --> cmfplone + multilingual -- depends on --> ploneapi + iterate -- depends on --> ploneapi + discussion -- depends on --> ploneapi + caching -- depends on --> ploneapi + exportimport -- uses serializers of --> restapi + exportimport -- depends on --> ploneapi + +``` ## Packages in detail From 68ff916a5928e7b77c999c7909f39351314b2a0e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 04:52:48 -0800 Subject: [PATCH 02/10] Update package-dependencies.md --- .../contributing/core/package-dependencies.md | 72 +++++++++---------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index 3ce4382f9..7d372e99e 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -25,22 +25,22 @@ There are multiple level of dependencies: - package level (`setup.py`/`setup.cfg`/`pyproject.toml`) - Python level (imports) -- ZCML level (includes) +- {term}`ZCML` level (includes) - testing (need for layers, such as functional testing) Circular dependencies at the package level have now been resolved. - Nevertheless there is indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. -## Mental model +## Mental model ### Borders -As a rough base mental model for how Plone is organized in Plone 6.1, there are two packages as dividing lines: +As a rough base mental model for how Plone is organized in Plone 6.1, there are two packages that serve as dividing lines. -1. `Products.CMFPlone` and all below defines the Plone core. Everything in here depends on the `plone.base`. +1. `Products.CMFPlone` and all below defines the Plone core. + Everything in here depends on the `plone.base`. 2. `plone.base` as the border to the Application Server and Content Management Framework and its dependencies ```{mermaid} @@ -68,33 +68,33 @@ block-beta ### Main components -Some explanation on the mental model - -- Foundation: - - `Zope` core and its dependencies is the application server, - - the Zope component architecture (ZCA) framework and - - some additional packages from the wider Zope ecosystem. - - then there are generic, standalone Plone libraries, - - plus various other Python libraries. -- `Products.CMFCore` provides on top of Zope very basic content management features we rely on. -- `plone.base` defines several interfaces as contracts for the component architecture we build on. - Additional it provides some base classes and utility functions we use often. - It also depends on `Products.CMFCore` and so `Zope`. - Additional it depends on generic functionality like `plone.dexterity`, `plone.behavior` and `plone.registry`. -- The space of plenty `plone.*`, `plone.app.*` and related libraries defines the core of Plone. -- On top of this core, depending on these packages, is `Products.CMFPlone` which is the package to depend on if the basic Plone core is referenced. -- On top of `Products.CMFPlone` - - are the core APIs like `plone.api` and `plone.restapi`, - - there is the distribution support `plone.distribution` and specific distributions, currently `plone.volto`, `plone.classicui`, - - are core addons like Working Copy Support (`plone.app.iterate`), discussion support (`plone.app.discussion`), ... - - is `plone.app.upgrade`, the package to upgrade between Plone version. -- The package `Plone` is the package to depend on if you want to depend on the whole Plone with everything. - This meta package without any code depends on all other packages. - It is what you want to install if you do not want to care about the details with all batteries included. - -### The space on top of CMFPlone - -Add-on developers and integrators are primary interacting with the dependencies on top of CMFPlone. +The following points describe the mental model. + +- Foundation: + - `Zope` core and its dependencies is the application server, + - the Zope component architecture (ZCA) framework and + - some additional packages from the wider Zope ecosystem. + - Then there are generic, standalone Plone libraries, + - plus various other Python libraries. +- `Products.CMFCore` provides very basic content management features on top of Zope on which Plone relies. +- `plone.base` defines several interfaces as contracts for the component architecture on which Plone is built. + Additionally it provides some base classes and utility functions that Plone often uses. + It also depends on `Products.CMFCore`, and therefore `Zope`. + Additionally it depends on generic functionality provided by `plone.dexterity`, `plone.behavior`, and `plone.registry`. +- The space of many `plone.*`, `plone.app.*`, and their related libraries defines the core of Plone. +- On top of this core, depending on these packages, is `Products.CMFPlone`, which is the package to depend on if the basic Plone core is referenced. +- On top of `Products.CMFPlone` are the following. + - The core APIs `plone.api` and `plone.restapi`. + - There is distribution support in `plone.distribution` and specific distributions, currently `plone.volto` and `plone.classicui`. + - Core add-ons include Working Copy Support from `plone.app.iterate`, discussion support (`plone.app.discussion`), and other add-ons. + - `plone.app.upgrade` is the package to upgrade between Plone version. +- If you want to depend on the whole Plone with everything, you should depend on the package `Plone`. + This meta package without any code depends on all other packages. + It is what you want to install if you don't care about the details and get "batteries included". + +### The space on top of `Products.CMFPlone` + +Add-on developers and integrators primarily interact with the dependencies on top of `Products.CMFPlone`. The following diagram visualizes this part. ```{mermaid} @@ -150,12 +150,11 @@ sankey-beta plone.api,Core,160 Plone,Upgrade,20 - ``` -## A more detailed view on the architecture +## Detailed view of the architecture -A more detailed view on the whole architecture is sketched here: +A more detailed view of the whole architecture is sketched here: ```{mermaid} flowchart TB @@ -214,12 +213,11 @@ flowchart TB caching -- depends on --> ploneapi exportimport -- uses serializers of --> restapi exportimport -- depends on --> ploneapi - ``` ## Packages in detail -Looking deeper into those packages, there are more sub-divisions, but first we place them into three groups: +Looking deeper into those packages, there are more sub-divisions, but first we place them into three groups. ### Above `Products.CMFPlone` From 760a794b70f88185047a8a93255b4d3862d43428 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 05:19:10 -0800 Subject: [PATCH 03/10] Bump mermaid version --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7de8f7153..59f385da4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -359,7 +359,7 @@ # -- Mermaid configuration ---------------------------------- -# mermaid_version = "10.9.1" +mermaid_version = "11.2.0" # -- OpenGraph configuration ---------------------------------- From cfd6f05a02ac668621e8cfe3f50e6173615ab708 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 05:28:25 -0800 Subject: [PATCH 04/10] Replace yaml with json config --- docs/contributing/core/package-dependencies.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index 7d372e99e..a79b51ecf 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -98,14 +98,7 @@ Add-on developers and integrators primarily interact with the dependencies on to The following diagram visualizes this part. ```{mermaid} ---- -config: - sankey: - showValues: false - width: 1600 - height: 800 - nodeAlignment: "right" ---- +:config: {"sankey": {"showValues": false, "width": 1600, "height": 800, "nodeAlignment": "right"}} sankey-beta From 48db8bfaf37cbac0b39a8c60ae8abb62277f6b1b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 05:38:13 -0800 Subject: [PATCH 05/10] Add attributes to Mermaid diagrams --- docs/contributing/core/package-dependencies.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index a79b51ecf..db9d6706a 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -44,6 +44,9 @@ As a rough base mental model for how Plone is organized in Plone 6.1, there are 2. `plone.base` as the border to the Application Server and Content Management Framework and its dependencies ```{mermaid} +:alt: Mental model of Plone +:caption: Mental model of Plone + block-beta columns 4 Plone["Plone
integraton of all in one release"]:4 @@ -96,9 +99,13 @@ The following points describe the mental model. Add-on developers and integrators primarily interact with the dependencies on top of `Products.CMFPlone`. The following diagram visualizes this part. +You can zoom in on the diagram. ```{mermaid} :config: {"sankey": {"showValues": false, "width": 1600, "height": 800, "nodeAlignment": "right"}} +:zoom: +:alt: Diagram of the space on top of Products.CMFPlone +:caption: Diagram of the space on top of Products.CMFPlone sankey-beta @@ -147,9 +154,14 @@ sankey-beta ## Detailed view of the architecture -A more detailed view of the whole architecture is sketched here: +The following diagram provides a more detailed view of the whole architecture of Plone. +You can zoom in on the diagram. ```{mermaid} +:zoom: +:alt: Architecture of Plone +:caption: Architecture of Plone + flowchart TB subgraph Release["Release"] Plone[["'Plone' Package"]] From b9d43dbbb9c14a1205fdd54f95e1c8eeb5346b21 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 18 Nov 2024 00:21:54 -0800 Subject: [PATCH 06/10] Move to Conceptual guides and reference from relevant documents. Update Overview with better labels and other minor corrections. --- docs/conceptual-guides/index.md | 1 + .../package-dependencies.md | 0 docs/contributing/core/index.md | 2 ++ docs/overview/index.md | 31 +++++++++++-------- 4 files changed, 21 insertions(+), 13 deletions(-) rename docs/{contributing/core => conceptual-guides}/package-dependencies.md (100%) diff --git a/docs/conceptual-guides/index.md b/docs/conceptual-guides/index.md index 0f48ba36e..9deeb7d80 100644 --- a/docs/conceptual-guides/index.md +++ b/docs/conceptual-guides/index.md @@ -18,6 +18,7 @@ This part of the documentation provides explanation of concepts to deepen and br choose-user-interface distributions package-management +package-dependencies make-build-backend-walk-through components ``` diff --git a/docs/contributing/core/package-dependencies.md b/docs/conceptual-guides/package-dependencies.md similarity index 100% rename from docs/contributing/core/package-dependencies.md rename to docs/conceptual-guides/package-dependencies.md diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 9a7ced788..1b2004561 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -168,7 +168,9 @@ git pull First identify the names of the Plone packages you want to work on. If you do not know, you can open an issue in the Plone GitHub repository for [`Products.CMFPlone`](https://github.com/plone/Products.CMFPlone/issues/), and someone might identify the source within a few days. +You can also read the conceptual guide {doc}`/conceptual-guides/package-dependencies` to get a mental model of the structure of Plone. You can also ask in the [Plone Community Forum](https://community.plone.org/). + Only a few packages are in {file}`src/` by default. Next create a new file {file}`buildout.local.cfg`, and add the names of packages that you want to develop under the `auto-checkout` list. diff --git a/docs/overview/index.md b/docs/overview/index.md index b612f3038..0018763b4 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -32,7 +32,7 @@ Plone works as a: - React-based frontend for editing and viewing content, backed by a server with a REST API. - Headless CMS server with a REST API, allowing a developer to build a custom frontend with their chosen technology. -(overview-3-label)= +(overview-key-benefits-label)= ## Key benefits @@ -67,9 +67,9 @@ Plone is easy to set up compared to other CMSs in its category, extremely flexib -(overview-4-label)= +(overview-high-level-overview-for-developers-label)= -## High Level Overview for Developers +## High level overview for developers Plone is a content management platform with its backend written in Python. It is built on top of the open source Zope web application server and development system. @@ -78,15 +78,15 @@ Throughout its history, Plone has used {term}`server-side rendering` to generate Additionally, Plone's use of a component architecture makes it easy to extend and customize, allowing users to create unique, feature rich websites that are tailored to their specific needs. With the release of Plone 6, you now have the option to choose from two different out-of-the-box supported configurations when setting up a new Plone website. -The Python-based backend server in Plone can still be used alone to render content server-side and deliver HTML to the browser, a setup that is referred to in the Plone documentation as "Classic UI". -This configuration has been supported by Plone since its initial release and is still available in the latest version of the platform. +The Python-based backend server in Plone can be used alone to render content server-side and deliver HTML to the browser, a setup that is referred to in the Plone documentation as "Classic UI". +This configuration has been supported by Plone since its initial release and is available in the latest version of the platform. For container-based deployment, only the `plone-backend` image is required. It may be used as a base image, adding customizations, to make a derivative image. -The default and recommended configuration for new websites in Plone is the new React-based JavaScript frontend called "Volto". +The latest configuration for new websites in Plone is the new React-based JavaScript frontend called "Volto". For this setup you still need to run the Python-based backend server, as well as enable the REST API, and update the configuration profile. These settings and profile are applied automatically when you select the {guilabel}`Create Plone Site` option in the Plone website creation form. -In addition a separate NodeJS based frontend server will serve the JavaScript frontend resources and provide {term}`SSR` with {term}`hydration`. +In addition, a separate Node.js based frontend server will serve the JavaScript frontend resources and provide {term}`SSR` with {term}`hydration`. To deploy this setup using containers, you will need the `plone-frontend` image for the frontend server. Beginning with Plone 6, we now support two programming language stacks, one each for Python and JavaScript. @@ -94,29 +94,34 @@ The documentation has been rewritten, but for this first release you will find s See, for example, the development setup and information on deployment options. It will take some time until we find and can implement the best structure to explain these new possibilities and the expansion of Plone's capabilities. +```{seealso} +You can also read the conceptual guide {doc}`/conceptual-guides/package-dependencies` to get a mental model of the structure of Plone. +``` ```{seealso} https://training.plone.org/mastering-plone/what_is_plone.html ``` -(overview-5-label)= +(overview-deployment-label)= + ## Deployment -To run a public Plone website in production, you will also need to configure and run a reverse proxy (or ingress), arrange for SSL certificates (either from Let's Encrypt or manually), guarantee persistence of the content database, and arrange backups. +To run a public Plone website in production, you also need to configure and run a reverse proxy (or ingress), arrange for SSL certificates (either from Let's Encrypt or manually), guarantee persistence of the content database, and arrange backups. This is the domain of systems administrators and modern developer-operations professionals. Our documentation contains setup examples for these services, yet requires that the reader have some generic experience and knowledge of these domains. -(overview-6-label)= -## Good to know / What to know +(overview-good-to-know-label)= + +## Good to know One of the key benefits of the new React-based frontend for Plone 6 is that you can now customize and theme Plone extensively using HTML, CSS, and JavaScript using up-to-date frontend technologies without having to set up a local Python development environment. The Plone backend can be run on a local developer machine in a container. Basic familiarity with programming in Python and managing Python modules and packages using `virtualenv` and `pip` is required to work on the backend code. -We use `virtualenv` and {term}`mxdev` to manage the source installation of packages in Plone 6. +We use `venv` and {term}`mxdev` to manage the source installation of packages in Plone 6. -Similarly, to develop for the new React frontend, you need to have some experience with setting up NodeJS, using a tool like NVM (Node Version Manager) to isolate your setup, and familiarity with {term}`Yarn` and {term}`React`. +Similarly, to develop for the new React frontend, you need to have some experience with setting up Node.js, using a tool like {term}`nvm` to isolate your setup, and familiarity with {term}`Yarn` and {term}`React`. If you are looking for more study material on these technologies beyond the documentation, see and follow one or more [Plone Trainings](https://training.plone.org). Our trainings are more verbose and contain extra clarification and examples. From 3e735a0963b4e46c3e317a6026903ce65ad4fc71 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 20 Nov 2024 02:10:28 -0800 Subject: [PATCH 07/10] Add examples of Mermaid diagram in contributing to Documentation Add `sphinxcontrib.mermaid` to extensions list --- .../documentation/myst-reference.md | 32 +++++++++++++++++++ .../documentation/themes-and-extensions.md | 1 + 2 files changed, 33 insertions(+) diff --git a/docs/contributing/documentation/myst-reference.md b/docs/contributing/documentation/myst-reference.md index e9d48224e..c3ff654cc 100644 --- a/docs/contributing/documentation/myst-reference.md +++ b/docs/contributing/documentation/myst-reference.md @@ -228,6 +228,38 @@ Example MyST syntax is shown below. ````` +### Diagrams and graphs with Mermaid + +You can use [Mermaid](https://mermaid.js.org/) and its Sphinx extension [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) to render graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts. + +````{example} +```{mermaid} +:alt: Mental model of Plone +:caption: Mental model of Plone +block-beta + columns 4 + Plone["Plone
integraton of all in one release"]:4 + Distributions + Upgrade + coreapis["Core APIs"] + coreaddons["Core add-ons"] + cmfplone["Products.CMFPlone"]:4 + ploneapp["Most of plone.app.* namespace"]:2 + otherlay["Various related packages"]:2 + plonebase["plone.base"]:4 + block:groupfoundation:4 + zopecore["Zope core/ ZCA"] + zopeeco["Zope ecosystem"] + cmfcore["CMFCore"] + ploneworld["Plone generic libraries"] + libraries["Other libraries"] + end + style cmfplone fill:#fff9e6 + style plonebase fill:#fff9e6 +``` +```` + + ### Diagrams and graphs with Graphviz We use [Graphviz](https://graphviz.org/download/) and its Sphinx extension [`sphinx.ext.graphviz`](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html) to render diagrams and graph visualizations. diff --git a/docs/contributing/documentation/themes-and-extensions.md b/docs/contributing/documentation/themes-and-extensions.md index 38642ad33..3ae0794dd 100644 --- a/docs/contributing/documentation/themes-and-extensions.md +++ b/docs/contributing/documentation/themes-and-extensions.md @@ -62,5 +62,6 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d - [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example. Supported tools include [curl](https://curl.se/), [wget](https://www.gnu.org/software/wget/), [httpie](https://httpie.io/), and [python-requests](https://requests.readthedocs.io/en/latest/). It is used by Plone's {doc}`/plone.restapi/docs/source/index`. +- [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) allows you to embed [Mermaid](https://mermaid.js.org/) graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts. - [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard. - [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/). From 366cd638b39e9c0e2e0b780cf3e9ce00ad326bf2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 Nov 2024 04:08:15 -0800 Subject: [PATCH 08/10] Italicize captions --- docs/conceptual-guides/package-dependencies.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conceptual-guides/package-dependencies.md b/docs/conceptual-guides/package-dependencies.md index db9d6706a..e7a5560ab 100644 --- a/docs/conceptual-guides/package-dependencies.md +++ b/docs/conceptual-guides/package-dependencies.md @@ -45,7 +45,7 @@ As a rough base mental model for how Plone is organized in Plone 6.1, there are ```{mermaid} :alt: Mental model of Plone -:caption: Mental model of Plone +:caption: _Mental model of Plone_ block-beta columns 4 @@ -105,7 +105,7 @@ You can zoom in on the diagram. :config: {"sankey": {"showValues": false, "width": 1600, "height": 800, "nodeAlignment": "right"}} :zoom: :alt: Diagram of the space on top of Products.CMFPlone -:caption: Diagram of the space on top of Products.CMFPlone +:caption: _Diagram of the space on top of `Products.CMFPlone`_ sankey-beta @@ -161,6 +161,7 @@ You can zoom in on the diagram. :zoom: :alt: Architecture of Plone :caption: Architecture of Plone +:caption: _Architecture of Plone_ flowchart TB subgraph Release["Release"] From 35eb191f02d72b06a6743d095d72d88d76201a7b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 Nov 2024 04:10:16 -0800 Subject: [PATCH 09/10] Add styles to theme of Architecture of Plone diagram --- docs/conceptual-guides/package-dependencies.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/conceptual-guides/package-dependencies.md b/docs/conceptual-guides/package-dependencies.md index e7a5560ab..1eba1756e 100644 --- a/docs/conceptual-guides/package-dependencies.md +++ b/docs/conceptual-guides/package-dependencies.md @@ -158,11 +158,21 @@ The following diagram provides a more detailed view of the whole architecture of You can zoom in on the diagram. ```{mermaid} +:config: {"theme": "base", "darkMode": "true"} :zoom: :alt: Architecture of Plone -:caption: Architecture of Plone :caption: _Architecture of Plone_ +%%{ + init: { + 'theme': 'base', + 'themeVariables': { + 'primaryColor': '#fefefe', + 'lineColor': '#aaa' + } + } +}%% + flowchart TB subgraph Release["Release"] Plone[["'Plone' Package"]] From 71d63161e6f3545bb88c240948f5520663beb786 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 Nov 2024 15:19:09 -0800 Subject: [PATCH 10/10] Minor grammar and spelling fixes --- .../conceptual-guides/package-dependencies.md | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/conceptual-guides/package-dependencies.md b/docs/conceptual-guides/package-dependencies.md index 1eba1756e..a3e3bd5c4 100644 --- a/docs/conceptual-guides/package-dependencies.md +++ b/docs/conceptual-guides/package-dependencies.md @@ -3,11 +3,11 @@ myst: html_meta: "description": "This chapter describes the architecture of Plone's packages and dependencies." "property=og:description": "This chapter describes the architecture of Plone's packages and dependencies." - "property=og:title": "Architecture: packages and dependecies" - "keywords": "Architecture, packages, dependecies, Plone" + "property=og:title": "Architecture: packages and dependencies" + "keywords": "Architecture, packages, dependencies, Plone" --- -# Architecture: packages and dependecies +# Architecture: packages and dependencies This chapter describes the architecture of Plone's packages and dependencies. @@ -29,19 +29,22 @@ There are multiple level of dependencies: - testing (need for layers, such as functional testing) Circular dependencies at the package level have now been resolved. -Nevertheless there is indirection on all other levels. +Nevertheless, there is indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. ## Mental model +This section describes a mental model that organizes Plone 6.1 packages into three groups separated by two packages that define the borders between these groups. + + ### Borders -As a rough base mental model for how Plone is organized in Plone 6.1, there are two packages that serve as dividing lines. +In Plone 6.1, there are two packages that serve as dividing lines. -1. `Products.CMFPlone` and all below defines the Plone core. +1. `Products.CMFPlone` and all packages below it define the Plone core. Everything in here depends on the `plone.base`. -2. `plone.base` as the border to the Application Server and Content Management Framework and its dependencies +2. `plone.base` is the border between the Application Server and Content Management Framework (CMF) with its dependencies. ```{mermaid} :alt: Mental model of Plone @@ -81,20 +84,21 @@ The following points describe the mental model. - plus various other Python libraries. - `Products.CMFCore` provides very basic content management features on top of Zope on which Plone relies. - `plone.base` defines several interfaces as contracts for the component architecture on which Plone is built. - Additionally it provides some base classes and utility functions that Plone often uses. + Additionally, it provides some base classes and utility functions that Plone often uses. It also depends on `Products.CMFCore`, and therefore `Zope`. - Additionally it depends on generic functionality provided by `plone.dexterity`, `plone.behavior`, and `plone.registry`. + Additionally, it depends on generic functionality provided by `plone.dexterity`, `plone.behavior`, and `plone.registry`. - The space of many `plone.*`, `plone.app.*`, and their related libraries defines the core of Plone. - On top of this core, depending on these packages, is `Products.CMFPlone`, which is the package to depend on if the basic Plone core is referenced. - On top of `Products.CMFPlone` are the following. - The core APIs `plone.api` and `plone.restapi`. - There is distribution support in `plone.distribution` and specific distributions, currently `plone.volto` and `plone.classicui`. - Core add-ons include Working Copy Support from `plone.app.iterate`, discussion support (`plone.app.discussion`), and other add-ons. - - `plone.app.upgrade` is the package to upgrade between Plone version. + - `plone.app.upgrade` is the package to upgrade between Plone versions. - If you want to depend on the whole Plone with everything, you should depend on the package `Plone`. This meta package without any code depends on all other packages. It is what you want to install if you don't care about the details and get "batteries included". + ### The space on top of `Products.CMFPlone` Add-on developers and integrators primarily interact with the dependencies on top of `Products.CMFPlone`. @@ -152,6 +156,7 @@ sankey-beta Plone,Upgrade,20 ``` + ## Detailed view of the architecture The following diagram provides a more detailed view of the whole architecture of Plone. @@ -231,9 +236,10 @@ flowchart TB exportimport -- depends on --> ploneapi ``` + ## Packages in detail -Looking deeper into those packages, there are more sub-divisions, but first we place them into three groups. +Looking deeper into those packages, there are more subdivisions which fall into three groups. ### Above `Products.CMFPlone`