Cookieplone Templates

About

This project is a collection of templates for Plone integrators to use through Cookieplone.

Installation 💾

Set up your system with Plone's Prerequisites for installation.

Choose a template 🛠️

Select a template with the following command:

uvx cookieplone

[1/1] Select a template
  1 - Volto Project
  2 - Classic UI Project
  3 - Backend Add-on for Plone
  4 - Frontend Add-on for Plone
  5 - Documentation scaffold for Plone projects

Template	Description	README.md
Volto Project	Create a new Plone project that uses the Volto frontend.	Read more
Classic UI Project	Create a new Plone project that uses Classic UI.	Read More
Backend Add-on for Plone	Create a new Python package to be used with Plone.	Read more
Frontend Add-on for Plone	Create a new Node.js package to be used with Volto.	Read more
Documenation scaffold	Create a documentation scaffold for your package.	Read more

Contribute 🤝

We welcome contributions to cookieplone-templates.

You can create an issue in the issue tracker, or contact a maintainer.

• Issue Tracker
• Source Code

Development requirements

See Installation.

For source control through Git and continuous integration and delivery (CI/CD), you'll also need a Git repository either under your personal or organization's account. Both GitHub and GitLab are currently supported Git repository and CI/CD service providers. However, only GitHub is currently supported for documentation hosting.

Setup

Create a local Python virtual environment with the following command.

make install

Run the checked out branch of cookieplone-templates.

COOKIEPLONE_REPOSITORY=~/YOUR_PATH_TO/cookieplone-templates uvx cookieplone project --no-input

Run a remote branch of cookieplone-templates.

COOKIEPLONE_REPOSITORY_TAG=<REMOTE_BRANCH_NAME> uvx cookieplone

Format the codebase

make format

Format the templates

make format_templates

Run tests

pytest is this package's test runner.

Run all tests with the following command.

make test

Run all tests, but stop on the first error and open a pdb session with the following command.

uv run pytest -x --pdb

Run only tests that match test_template_has_required_keys with the following command.

uv run pytest -k test_template_has_required_keys

Run only tests that match test_template_has_required_keys, but stop on the first error and open a pdb session with the following command.

uv run pytest -k test_template_has_required_keys -x --pdb

Publish to Git service provider

To publish your project to your Git service provider, first create an empty remote repository with your Git service provider. Then navigate to the root of your generated project folder. Finally, issue the following commands.

Note

If your remote repository is private, you'll need to manage authorization when you push commits upstream.

git status
git commit -m "first commit"
git remote add origin https://<git_service_provider>/<organization_or_username>/<project_slug>.git
git branch -M main
git push

Your remote repository should now be populated with your generated project.

Publish documentation to Read the Docs

The Cookieplone template documentation_starter supports publishing documentation and pull request preview builds on Read the Docs.

First, create an account on Read the Docs, then follow their documentation to add a documentation project and configure pull request previews.

• Adding a documentation project
• How to configure pull request builds
• Pull request previews

Next, update your documentation files. Search for the string MY_READTHEDOCS_PROJECT_SLUG throughout your project, and replace it your project's slug that Read the Docs assigned to your project.

Finally, commit and push your changes to your remote repository.

Read the Docs will build documentation and with the next pull request, will build a pull request preview and insert a link to the preview in your pull request.

Note

It's currently not supported to check for a unique slug on Read the Docs before generating your project, especially if you set up a private repository.

License 📜

This project is licensed under the MIT License.

Let's get building! 🚀

Happy coding!