Migrate docs from Plone 5 to Plone 6 based on TODOs #1917

Manas-Kenge · 2025-03-17T17:04:45Z

Issue number

Ref Purge empty pages and todos #1882

Description

https://6.docs.plone.org/backend/behaviors.html#built-in-behaviors TODO
https://6.docs.plone.org/backend/subscribers.html Migrate docs from Plone 5 to Plone 6
https://6.docs.plone.org/backend/upgrading/preparations.html#back-up-your-plone-site TODO
https://6.docs.plone.org/conceptual-guides/package-management.html#manage-frontend-node-js-packages TODO

📚 Documentation preview 📚: https://plone6--1917.org.readthedocs.build/

stevepiercy

My apologies for not providing clear direction about the TODOs. I edited the issue description and added a comment here to clarify.

I will need to do a more thorough review later, but these suggestions should be incorporated now. Thank you!

stevepiercy · 2025-03-17T21:44:06Z

docs/backend/behaviors.md

Sorry, I realized the original description was not clear. I updated it just now. Please revert changes in this file. Instead set the configuration values in conf.py, changing code from the following...

documentation/docs/conf.py

Lines 381 to 385 in b4462a8

# -- Options for sphinx.ext.todo -----------------------

# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos

todo_include_todos = True

...to the following.

# -- Options for sphinx.ext.todo ----------------------- # See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos todo_include_todos = False todo_emit_warnings = True todo_link_only = True

Ref: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

Since this TODO already contains a link to an existing issue, we do not need to create an issue or add a link to the issue.

stevepiercy · 2025-03-17T21:45:28Z

docs/backend/upgrading/preparations.md

-```{seealso}
-See Plone 5.2 documentation, [Backing up your Plone deployment](https://5.docs.plone.org/manage/deploying/backup.html).


Revert. This was deliberate.

stevepiercy · 2025-03-17T21:45:52Z

docs/backend/upgrading/preparations.md


-```{seealso}
-See Plone 5.2 documentation, [Backing up your Plone deployment](https://5.docs.plone.org/manage/deploying/backup.html).
+### Introduction


Suggested change

### Introduction

```

### Introduction

stevepiercy · 2025-03-17T21:47:19Z

docs/conceptual-guides/package-management.md

-```{todo}
-Why do we use pnpm?
-```


Revert, create an issue if one does not already exist either in Documentation or Volto repo, and add its link here.

stevepiercy · 2025-03-17T21:49:44Z

@plone/classicui-team could I get a technical review from y'all? Thank you!

jensens

I think this PR should be split for each file in a separate PR.
I only reviewed the subscribers part and its some work to get it right.

jensens · 2025-03-18T10:24:41Z

docs/backend/subscribers.md

+Some of the notable characteristics of the Plone event system are:
+
+- It is simple;
+- Subscriber calling order is not modifiable — you cannot set the order in which event handlers are called;


Something like this? Otherwise second part is kind of a dup of the first.

Suggested change

- Subscriber calling order is not modifiable — you cannot set the order in which event handlers are called;

- Subscriber calling is random — you cannot set the order in which event handlers are called;

jensens · 2025-03-18T10:26:14Z

docs/backend/subscribers.md

+- Globally (no scope)
+- Per content type
+


Suggested change

- Globally (no scope)

- Per content type

- Globally (no scope)

- Per content type

- per behavior/ marker interface

jensens · 2025-03-18T10:30:55Z

docs/backend/subscribers.md

+    handler=".your_python_file.your_method"
+    />
+```
+The first line defines to which interface you want to bind the execution of your code, which means here, that the code will only be executed if the object is one of your contenttype’s. If you want this to be interface-agnostic, insert an asterix as a wildcard instead.


Suggested change

The first line defines to which interface you want to bind the execution of your code, which means here, that the code will only be executed if the object is one of your contenttype’s. If you want this to be interface-agnostic, insert an asterix as a wildcard instead.

The second line defines to which interface you want to bind the execution of your code.

Here, the event handler code will only be executed if the object is a content-type providing the interface `.interfaces.IMyContentTypeClass`.

If you want this to be interface-agnostic, insert an asterix `*` as a wildcard instead.

jensens · 2025-03-18T10:31:16Z

docs/backend/subscribers.md

+### Example: Register an event-handler on your content type’s creation
+
+In your `.product/your/product/configure.zcml` insert:
+```


append XML for syntax highlighting

jensens · 2025-03-18T10:33:16Z

docs/backend/subscribers.md

+```
+The first line defines to which interface you want to bind the execution of your code, which means here, that the code will only be executed if the object is one of your contenttype’s. If you want this to be interface-agnostic, insert an asterix as a wildcard instead.
+
+The second line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’ – for Archetypes you should use ‘Products.Archetypes.interfaces.IObjectInitializedEvent’ instead. For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)


No Archetypes anymore.

Suggested change

The second line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’ – for Archetypes you should use ‘Products.Archetypes.interfaces.IObjectInitializedEvent’ instead. For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)

The third line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’.

For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)

The URL should not be absolute here I suppose?

jensens · 2025-03-18T10:33:59Z

docs/backend/subscribers.md

+
+The second line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’ – for Archetypes you should use ‘Products.Archetypes.interfaces.IObjectInitializedEvent’ instead. For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)
+
+The third line gives the path to the script that is supposed to be executed.


Suggested change

The third line gives the path to the script that is supposed to be executed.

The fourth line gives the path to the callable (function) that is supposed to be executed.

jensens · 2025-03-18T10:34:52Z

docs/backend/subscribers.md

+
+Create your `.product/your/product/your_python_file.py` and insert:
+```
+def your_method(object, event):


Its a function and it does not help much, tell the reader what it is: a subscriber

Suggested change

def your_method(object, event):

def your_subscriber(object, event):

jensens · 2025-03-18T10:35:24Z

docs/backend/subscribers.md

+
+    # do sth with your created contenttype


Suggested change

# do sth with your created contenttype

...

# do sth with your created contenttype

jensens · 2025-03-18T10:37:26Z

docs/backend/subscribers.md

+`Products.Archetypes.interfaces.IObjectInitializedEvent` is fired for an Archetypes-based object when it’s being initialised; i.e. when it’s being populated for the first time.
+
+`Products.Archetypes.interfaces.IWebDAVObjectInitializedEvent` is fired for an Archetypes-based object when it’s being initialised via WebDAV.


remove all archetypes

jensens · 2025-03-18T10:38:30Z

docs/backend/subscribers.md

+
+`zope.processlifetime.IDatabaseOpened` is triggered after the main ZODB database has been opened.
+
+## Event handlers


this is more conceptional, right?

Manas-Kenge · 2025-03-18T14:29:59Z

I think this PR should be split for each file in a separate PR. I only reviewed the subscribers part and its some work to get it right.

@jensens I'll create a separate PR for the other files. I copied the docs from Plone 5 but wasn't sure which parts were deprecated or still functional. Sorry for the extra work.

jensens · 2025-03-18T16:39:30Z

I think this PR should be split for each file in a separate PR. I only reviewed the subscribers part and its some work to get it right.

@jensens I'll create a separate PR for the other files. I copied the docs from Plone 5 but wasn't sure which parts were deprecated or still functional. Sorry for the extra work.

Thanks for your work! I am looking forward to review again!

Manas-Kenge · 2025-03-19T05:19:51Z

Closing this PR to open separate ones.

migrate content from plone 5 to 6

c60b36a

Manas-Kenge changed the title ~~migrate content from plone 5 to 6~~ Migrate docs from Plone 5 to Plone 6 based on TODOs Mar 17, 2025

stevepiercy requested changes Mar 17, 2025

View reviewed changes

stevepiercy requested review from davisagli and jensens March 17, 2025 21:49

jensens requested changes Mar 18, 2025

View reviewed changes

Manas-Kenge closed this Mar 19, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate docs from Plone 5 to Plone 6 based on TODOs #1917

Migrate docs from Plone 5 to Plone 6 based on TODOs #1917

Manas-Kenge commented Mar 17, 2025 •

edited by github-actions bot

Loading

stevepiercy left a comment

stevepiercy Mar 17, 2025

stevepiercy Mar 17, 2025

stevepiercy Mar 17, 2025

stevepiercy Mar 17, 2025

stevepiercy commented Mar 17, 2025

jensens left a comment

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

jensens Mar 18, 2025

Manas-Kenge commented Mar 18, 2025

jensens commented Mar 18, 2025

Manas-Kenge commented Mar 19, 2025

	# -- Options for sphinx.ext.todo -----------------------

	# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
	todo_include_todos = True

		```{seealso}
		See Plone 5.2 documentation, [Backing up your Plone deployment](https://5.docs.plone.org/manage/deploying/backup.html).

	- Subscriber calling order is not modifiable — you cannot set the order in which event handlers are called;
	- Subscriber calling is random — you cannot set the order in which event handlers are called;

-The first line defines to which interface you want to bind the execution of your code, which means here, that the code will only be executed if the object is one of your contenttype’s. If you want this to be interface-agnostic, insert an asterix as a wildcard instead.
+The second line defines to which interface you want to bind the execution of your code.
+Here, the event handler code will only be executed if the object is a content-type providing the interface `.interfaces.IMyContentTypeClass`.
+If you want this to be interface-agnostic, insert an asterix `*` as a wildcard instead.

	The second line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’ – for Archetypes you should use ‘Products.Archetypes.interfaces.IObjectInitializedEvent’ instead. For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)
	The third line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’.
	For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)


		The second line defines the event on which this should happen, which is here ‘IObjectCreatedEvent’ – for Archetypes you should use ‘Products.Archetypes.interfaces.IObjectInitializedEvent’ instead. For more available possible events to be used as a trigger, see [Event handlers](https://6.docs.plone.org/backend/subscribers.html#event-handlers)

		The third line gives the path to the script that is supposed to be executed.

	The third line gives the path to the script that is supposed to be executed.
	The fourth line gives the path to the callable (function) that is supposed to be executed.

	def your_method(object, event):
	def your_subscriber(object, event):

		`Products.Archetypes.interfaces.IObjectInitializedEvent` is fired for an Archetypes-based object when it’s being initialised; i.e. when it’s being populated for the first time.

		`Products.Archetypes.interfaces.IWebDAVObjectInitializedEvent` is fired for an Archetypes-based object when it’s being initialised via WebDAV.


		`zope.processlifetime.IDatabaseOpened` is triggered after the main ZODB database has been opened.

		## Event handlers

Migrate docs from Plone 5 to Plone 6 based on TODOs #1917

Migrate docs from Plone 5 to Plone 6 based on TODOs #1917

Conversation

Manas-Kenge commented Mar 17, 2025 • edited by github-actions bot Loading

Issue number

Description

stevepiercy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevepiercy commented Mar 17, 2025

jensens left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Manas-Kenge commented Mar 18, 2025

jensens commented Mar 18, 2025

Manas-Kenge commented Mar 19, 2025

Manas-Kenge commented Mar 17, 2025 •

edited by github-actions bot

Loading