From f1bd2ca7dde26f17041788d6893fa9d6d85c2f03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Thu, 25 Apr 2024 22:46:51 -0300 Subject: [PATCH] Update README.md (#11) * Update README.md (Fixes #8) * Tidy up the README.md * Add Changelog entry * Fix alt text * Switch from PyPI broken license Shields.io badge to GitHub --------- Co-authored-by: Steve Piercy --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++- news/8.documentation | 1 + 2 files changed, 144 insertions(+), 3 deletions(-) create mode 100644 news/8.documentation diff --git a/README.md b/README.md index 12dc357..34aef4d 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

- cookieplone + Cookieplone 🍪

@@ -12,13 +12,153 @@ [![PyPI](https://img.shields.io/pypi/v/cookieplone)](https://pypi.org/project/cookieplone/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cookieplone)](https://pypi.org/project/cookieplone/) [![PyPI - Wheel](https://img.shields.io/pypi/wheel/cookieplone)](https://pypi.org/project/cookieplone/) -[![PyPI - License](https://img.shields.io/pypi/l/cookieplone)](https://pypi.org/project/cookieplone/) +[![PyPI - License](https://img.shields.io/github/license/Plone/cookieplone)](https://pypi.org/project/cookieplone/) [![PyPI - Status](https://img.shields.io/pypi/status/cookieplone)](https://pypi.org/project/cookieplone/) - [![Tests](https://github.com/plone/cookieplone/actions/workflows/main.yml/badge.svg)](https://github.com/plone/cookieplone/actions/workflows/main.yml) [![GitHub contributors](https://img.shields.io/github/contributors/plone/cookieplone)](https://github.com/plone/cookieplone) [![GitHub Repo stars](https://img.shields.io/github/stars/plone/cookieplone?style=social)](https://github.com/plone/cookieplone) + +Welcome to Cookieplone, a powerful wrapper around Cookiecutter designed to streamline the development of Plone codebases. +Whether you're building a backend add-on, a new Volto add-on, a full project with both backend and frontend, or even documentation, Cookieplone simplifies the process using robust Cookiecutter templates. + +## Key features 🌟 + +Cookieplone offers the following key features for each audience. + +### For users + +- **One stop for all Plone templates**: Cookieplone helps you find the correct template to start your new Plone project. +- **Simplified usage**: Cookieplone provides an enhanced experience over standard Cookiecutter usage by offering predefined sane defaults and a unified approach to generating various Plone projects. +- **Batteries included**: No need to install lots of dependencies. Run `pipx run cookieplone`, and you will quickly generate your codebase. + + +### For template creators + +- **Built-in validators**: Includes built-in validators to ensure user inputs are correct. +- **Jinja2 filters**: Includes Jinja2 filters for advanced template control. +- **Sub-templates**: Mechanism to easily instantiate "sub templates" within cookiecutter hooks -- i.e. post_gen_hook -- , facilitating greater code reuse. + + +## Installation 💾 + +First, ensure you have Python, pip, and pipx installed on your system. + +Then install Cookieplone using `pipx`: + +```shell +# pipx is strongly recommended. +pipx install cookieplone +``` + +Or, if pipx is not an option, you can install Cookieplone in your Python user directory. + +```shell +python -m pip install --user cookieplone +``` + +## Usage 🛠️ + +To see all available template options, run: + +```shell +pipx run cookieplone +``` + +Cookieplone will walk you through the necessary steps, using sensible defaults and offering customization options where needed. + +### Specify a template + +You can also specify other templates. + +| Template | Description | Command | +| --- | --- | --- | +| **project** | Create a Plone project with Backend and frontend. | `pipx run cookieplone project ` | +| **plone_addon** | Create a Plone add-on to be used with the backend. | `pipx run cookieplone plone_addon ` | +| **volto_addon** | Create a Plone add-on to be used with the frontend. | `pipx run cookieplone volto_addon ` | + +### Configure Cookieplone + +| Environment Variable | Description | Example | +| --- | --- | --- | +| **COOKIEPLONE_REPOSITORY** | Where to look for templates to be used. | `COOKIEPLONE_REPOSITORY=/home/plone/cookiecutter-plone/ pipx run cookieplone` | +| **COOKIEPLONE_REPOSITORY_REF** | Which tag/branch to use from a remote repository. | `COOKIEPLONE_REPOSITORY_REF=experimental pipx run cookieplone` | +| **COOKIEPLONE_REPO_PASSWORD** | Password to use when using a remote repository that is password protected. | `COOKIEPLONE_REPO_PASSWORD=very-secure pipx run cookieplone` | + +## Contribute 🤝 + +We welcome contributions to Cookieplone. + +You can create an issue in the issue tracker, or contact a maintainer. + +- [Issue Tracker](https://github.com/plone/cookieplone/issues) +- [Source Code](https://github.com/plone/cookieplone/) + +### Development requirements + +- Python 3.10 or later +- [Hatch](https://hatch.pypa.io/) + +### Setup + +Install all development dependencies, including Hatch, and create a local virtual environment with the following command. + +```shell +make install +``` + +### Check and format the codebase + +```shell +make check +``` + +### Run tests + +[`pytest`](https://docs.pytest.org/) is this package's test runner. + +Run all tests with the following command. + +```shell +make test +``` + +Run all tests, but stop on the first error and open a `pdb` session with the following command. + +```shell +hatch run test -x --pdb +``` + +Run only tests that match `test_run_sanity_checks_fail` with the following command. + +```shell +hatch run test -k test_run_sanity_checks_fail +``` + +Run only tests that match `test_run_sanity_checks_fail`, but stop on the first error and open a `pdb` session with the following command. + +```shell +hatch run test -k test_run_sanity_checks_fail -x --pdb +``` + +## Support 📢 + +For support, questions, or more detailed documentation, visit the [official Cookieplone repository](https://github.com/plone/cookieplone). + +Thank you for choosing Cookieplone for your Plone development needs! + + +## This project is supported by + +

+ + Plone Foundation Logo + +

+ +## License + +The project is released under the [MIT License](./LICENSE). diff --git a/news/8.documentation b/news/8.documentation new file mode 100644 index 0000000..0de8722 --- /dev/null +++ b/news/8.documentation @@ -0,0 +1 @@ +Initial documentation (README.md) for cookieplone [@ericof]