DEV: add description on creating a frontend project with cookieplone an…

[animus888]

…d add some howtos (add-ons, theme, logo)

Description

documentation part on creating a project with cookiecutter-volto and add some howtos (add-ons, theme, logo).

[netlify]

✅ Deploy Preview for 6-docs-plone-org ready!

Name	Link
🔨 Latest commit	e57b1ab
🔍 Latest deploy log	https://app.netlify.com/sites/6-docs-plone-org/deploys/66459d1976c4560007e6c914
😎 Deploy Preview	https://deploy-preview-1649--6-docs-plone-org.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[davisagli]

Thanks for working on documentation, but I'm worried it could be confusing to add docs about a tool that's in experimental status. I think the general plan is to make cookiecutter-plone-starter use cookiecutter-volto once we're confident that that works well, and then it won't be necessary to use cookiecutter-volto directly unless you're in the specific situation of wanting a new frontend to use with an existing backend.

[animus888]

@davisagli Thank you for the information.
May I ask why it is planned in future that users should work with cookiecutter-volto through cookiecutter-plonestarter ?
Or are there any special reasons why users shouldn't use cookiecutter-volto directly?
I just thought it would be an effort to get cookiecutter-volto working through cookiecutter-plonestarter.
Wouldn't it be easier to simply replace cookiecutter-plonestarter with cookiecutter-volto in future?

[stevepiercy]

@davisagli the purpose of this PR, as discussed at the Alpine Sprint, is to publish a how-to guide for cookiecutter-volto. We settled on Plone 6 Documentation, but with a clear "experimental" indicator. This provides the following advantages.

1. It gives cookiecutter-volto exposure that it otherwise would not get, especially to newcomers.
2. It reuses includes from other parts of the documentation for pre-requisites.
3. It reuses the documentation infrastructure.
4. We don't want to replace the current Install instructions, but documenting this alternative can help us better inform what direction the cookiecutters ultimately take. Documentation will be a single place to run comparisons.

There was strong sentiment expressed at the Alpine Sprint that cookiecutter-volto would be the way of the future because of its simpler implementation, but you bring up a valid point which sows uncertainty that should be resolved before we commit to this direction. Clearly there needs to be further discussion about the future of cookiecutters amongst interested parties, and a road map should be agreed upon. I hope that happens, but not in this PR. Can you suggest who should be involved in that discussion, and perhaps take it to the Community Forum? Off the top of my head, I think that would include the following people and possibly others:

• @jensens
• @davisagli
• @ericof
• @sneridagh

Of course, and as always, we can revise and change tack to the changing winds. I want all of us to sail in the same direction on this ship.

[jensens]

IMO it is favorable to have the cookiecutters documented separately.

1. cookiecutter-plone-starter is supposed to be - as the name tells - a starter. But it is blown up a lot for this purpose btw. So, in fact its no more the small starter but overwhelms people and makes Plone (my opinion) look more complex than it is.
2. Then cookiecutter-volto is not only about bootstrapping a project, but also for addons and themes. So, I do not see why we would want to not teach people how to use it.
3. I am totally fine using it within the starter. As a tool.
4. The cookiecutter-volto on its own offers a full development environment for Volto. No starter needed, simple backend start in Docker. It reduces the complexity and lowers the entry barrier a lot.
5. Last but not least I am a fan of small tools doing one thing.

[stevepiercy]

I made suggestions to re-order and restructure a few things. We should do at least one more pass, to make sure it flows properly.

[davisagli]

@stevepiercy @jensens I think we basically agree on most of how you are thinking about cookiecutter-volto, and I withdraw my objection to adding this documentation. However, I have one request which I'll explain below.

As a general strategy I think it makes sense to have high-quality (tested, documented) scaffolds focused on particular pieces of our stack (i.e. Volto, the Plone backend, a deployment solution). There can even be multiple scaffolds for alternative approaches (i.e. one for a deployment using Docker Swarm, another for a deployment using Kubernetes...)

Then cookiecutter-plone-starter should become a wrapper that calls the other scaffolds as tools, for someone who is new and doesn't know what pieces they need. (This could also be a new cookiecutter if that's easier to accomplish, but I've been thinking about it as an evolution of cookiecutter-plone-starter.)

cookiecutter-plone-starter already uses this wrapper approach for generating a volto project using the yeoman-based generator. cookiecutter-volto is a clear improvement over that (because yeoman is not maintained well these days, and because cookiecutter-volto uses pnpm which makes it easier to develop a Volto addon along with other packages). So I've been assuming that we at least want to update cookiecutter-plone-starter to use cookiecutter-volto.

Anyway, my remaining request about this documentation is that I think it could use a clearer introduction which mentions when it would be appropriate to use cookiecutter-volto instead of the existing install docs based on cookiecutter-plone-starter. cookiecutter-volto is great if you are developing something that is frontend only (and just want to run a non-customized Plone backend via docker) but it doesn't give you everything you need if you also want to customize the backend and deploy the solution. Right?

[animus888]

@davisagli @stevepiercy @jensens I added the information that cookiecutter-volto currently only supports frontend development to the introduction see here.

[stevepiercy]

We are sprinting on the cookiecutters at the Axolote Sprint in Mexico City this week, and there may be more changes. I'll push commits to reflect any changes that arise.

[animus888]

We are sprinting on the cookiecutters at the Axolote Sprint in Mexico City this week, and there may be more changes. I'll push commits to reflect any changes that arise.

@davisagli @stevepiercy @jensens
pipx run cookieplone volto_addon throws an error.
And I expected it to install cookiecutter-volto.

If it really should run cookiecutter-volto for the volto_addon option.
Then I would update my documentation part --> "Create a volto_addon project with cookieplone (experimental)"

[ericof]

cookiecutter-volto is now deprecated.
To get the same features you should use pipx run cookieplone fromtend_addon

[stevepiercy]

@animus888 if you can make it to the Beethoven Sprint remotely in Discord, there is a daily stand-up at 9:30 AM CET, and a 24/7 chat channel at https://discord.com/channels/786421998426521600/971310680114360340. There has been more progress on the cookiecutters, and things might change again. It would be good to chat with the core developers on this item, especially because they want feedback on its usage.

[animus888]

@animus888 if you can make it to the Beethoven Sprint remotely in Discord, there is a daily stand-up at 9:30 AM CET, and a 24/7 chat channel at https://discord.com/channels/786421998426521600/971310680114360340. There has been more progress on the cookiecutters, and things might change again. It would be good to chat with the core developers on this item, especially because they want feedback on its usage.

@stevepiercy
I've seen it too late 😿
Today I tried re-creating my frontend project using cookieplone with the frontend add-on template and it seems to work so far 👍