Cookieplone Templates

About

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

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.

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

Releasing 🏷️

Releases of cookieplone-templates use CalVer versioning in the format YYYYMMDD.N, where N is a sequential counter that disambiguates multiple releases on the same day (e.g. 20260319.1).

Each release:

• Generates and commits a changelog from towncrier news fragments.
• Creates a Git tag matching the version.
• Publishes a GitHub release with the changelog as its body.

Preview the changelog

Before releasing, preview what the changelog will look like without making any changes:

make changelog

Publish a new release

When ready to release, run:

make release

This will:

1. Determine the next CalVer version.
2. Show a changelog preview and prompt for confirmation.
3. Generate and commit the changelog.
4. Push the tag to the remote.
5. Create the GitHub release.

Note

A valid GITHUB_TOKEN with write access to the repository must be present in your environment.

License 📜

This project is licensed under the MIT License.

Let's get building! 🚀

Happy coding!