Reorganize Classic UI Theming part

[stevepiercy]

Closes #1645

---

📚 Documentation preview 📚: https://plone6--1831.org.readthedocs.build/classic-ui/theming/index.html

[stevepiercy]

@plone/classicui-team please review.

[stevepiercy]

First person to review this PR gets a 🍪 !

@petschki
@yurj
@MrTango
@jensens
@1letter

It has one section where I need some help to clarify it, please!

[stevepiercy]

We have to ignore the pull request preview build failure for a while. I just filed an issue with RTD at readthedocs/readthedocs.org#11912

[petschki]

I'm happy with the restructuring here. Thank you!

[petschki]

Where's my 🍪 😉

[stevepiercy]

Where's my 🍪 😉

I'll bring a batch for the next PloneConf or sprint. 😁

I need help with this TODO, as I don't have the experience or knowledge. If y'all can give me some notes, I can wordsmith something together.

https://plone6--1831.org.readthedocs.build/classic-ui/theming/index.html

[stevepiercy]

@petschki @yurj @MrTango @jensens @1letter

I need help with this TODO about choosing a theming method, as I don't have the experience or knowledge. If y'all can give me some notes or guidance, I can wordsmith something together and finish up this PR.

https://plone6--1831.org.readthedocs.build/classic-ui/theming/index.html

Thank you!

[ale-rt]

@stevepiercy what about merging master and merging this PR with the TODO?
We can add it later.

[stevepiercy]

@ale-rt we've tried that, and it doesn't work. A little bit of evidence:

• https://6.docs.plone.org/classic-ui/forms.html
• https://6.docs.plone.org/classic-ui/templates.html
• https://6.docs.plone.org/backend/annotations.html
• https://6.docs.plone.org/backend/configuration-registry.html
• https://6.docs.plone.org/backend/search.html
• https://6.docs.plone.org/backend/security.html
• https://6.docs.plone.org/backend/sending-email.html
• https://6.docs.plone.org/backend/subscribers.html
• https://6.docs.plone.org/backend/users-groups.html
• https://6.docs.plone.org/backend/vocabularies.html
• https://6.docs.plone.org/backend/workflows.html
• https://6.docs.plone.org/backend/zodb.html

There's also the embarrassment of completing only 13% of Plone 6.0 and 6.1 documentation issues at the time of Plone 6.1 release.

[stevepiercy]

@petschki @yurj @MrTango @jensens @1letter

I need help with this TODO about choosing a theming method, as I don't have the experience or knowledge. If y'all can give me some notes or guidance, I can wordsmith something together and finish up this PR.

Since I got no response, I'm inclined to refer readers to get help to make a choice in the Classic UI Community Forum topic and Discord channel.

I'll revisit this when I get some time, but it can't be merged until helpful content replaces the todo.

[jensens]

I think that TTW is likely for testing or small-scale changes, especially for short-lived or prototype sites. It allows you to make minor adjustments without needing to dive into code or production-level setups. TTW can be convenient for quick experiments, for websites that don't require complex theming or short-lived websites.

Add-ons are definitely suited for production environments. An add-on allows you to keep your customization modular, and it provides a more structured approach to larger-scale theming. This method is ideal for more permanent or complex customizations since it enables easier maintenance and portability.

The customized Barceloneta theme, using Diazo, and creating a theme from scratch offer even more flexibility:

• Barceloneta theme: Ideal for a starting point, especially if you want to tweak it as an existing, solid theme. You can customize its components and styles without starting from zero.

• From Scratch: If your project requires something completely unique and none of the existing themes fit, building a theme from scratch would be the way to go. This is most appropriate for highly customized websites with distinct design requirements.

• Diazo: Additional to an addon with customized or from-scratch and one of the more advanced methods. It offers control over the markup without customizing templates. It's great to have for more complex themes where content needs to remain flexible but you want full control over the markup. Disadvantage is possible slow down of the rendering process and more complex and more difficult to maintain theme.

In summary:

• Use TTW for minor changes or testing.
• Use Add-ons for production-level theming that needs scalability, maintainability, and modularity to customize Barceloneta or write from-scratch themes.
• Use Diazo in your addon if you need to modify the markup without touching the page-templates.

[stevepiercy]

@jensens that is beautiful. Thank you so much! I wordsmithed it into the index page in 95aeba3.

With that, I approve this PR, pending the merge of the related PR #1870 from @erral.

[stevepiercy]

Thank you @petschki, @jensens, and @erral for helping on this PR. Will merge at long last when it is all green.