diff --git a/README.md b/README.md index 84d7ce2..9594fe9 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,75 @@ # Welcome to Python Package Cookiecutter! -This repository is a template repository (a cookiecutter) that allows you to quickly -set up new Python packages. It is geared towards scientific applications and implements -the best practice guidelines of the [Scientific Software Center of Heidelberg University](https://ssc.iwr.uni-heidelberg.de). +This repository is a **template (cookiecutter)** for quickly setting up new Python packages. +It’s designed with **scientific applications** in mind and follows the best-practice guidelines of the [Scientific Software Center, Heidelberg University](https://ssc.iwr.uni-heidelberg.de). -# Features +--- -* Very simple, configurable setup of a fully functional project -* Modern build system metadata specification using `pyproject.toml` (PEP517 + PEP621) -* Based on an established tool: [Cookiecutter](https://github.com/cookiecutter/cookiecutter) has >17k stars on Github! -* Package versioning integrated with Git repository using `setuptools_scm` -* CI/CD configurations using Github Actions or Gitlab CI -* Sphinx documentation deployed to [readthedocs.org](https://readthedocs.org) +## Features -If your Python package contains compiled C++ modules, you might want to check out our [C++ Cookiecutter with Pybind11 bindings](https://github.com/ssciwr/cookiecutter-cpp-project) instead. +* **Simple and configurable setup** for a fully functional Python project +* **Modern build system** with `pyproject.toml` (PEP 517 + PEP 621) +* **Powered by [Cookiecutter](https://github.com/cookiecutter/cookiecutter)** — trusted by 17k+ developers +* **Automatic versioning** using `setuptools_scm` integrated with Git +* **CI/CD support** via GitHub Actions or GitLab CI +* **Sphinx documentation** with automatic deployment to [Read the Docs](https://readthedocs.org) -# Prerequisites +> If your Python package includes compiled C++ modules, check out our +> [C++ Cookiecutter with Pybind11 bindings](https://github.com/ssciwr/cookiecutter-cpp-project). -In order to use Python Package Cookiecutter you need the following software installed: +--- -* Python `>= 3.8` -* [Cookiecutter](https://github.com/cookiecutter/cookiecutter) e.g. by doing `pip install cookiecutter`. -* Git `>= 1.8.2` +## Prerequisites -# Using the Python Package Cookiecutter +To use Python Package Cookiecutter, make sure you have the following installed: -Simply run the cookiecutter command line interface: +* Python **≥ 3.8** +* [Cookiecutter](https://github.com/cookiecutter/cookiecutter) — install with: -``` + ```bash + pip install cookiecutter + ``` +* Git **≥ 1.8.2** + +--- + +## Getting Started + +Run the Cookiecutter command-line tool: + +```bash cookiecutter gh:ssciwr/cookiecutter-python-package ``` -This will start an interactive prompt that will configure and generate your project. -One of the prompts will ask you for a remote repository URL, so you should head to -the Git hosting service of your choice and add a new empty repository e.g. [on Github](https://github.com/new). +This launches an **interactive prompt** that helps you configure and generate your new project. + +One of the prompts will ask for a remote repository URL. +Before you begin, create an empty repository on your preferred Git hosting service, e.g. [GitHub](https://github.com/new). + +--- + +## Configuration Options -# Configuration +You’ll be asked to provide the following configuration values: -This cookiecutter accepts the following configuration options: +| Option | Description | Default | +| ---------------------- | ------------------------------------------------------------- | --------------------------- | +| `project_name` | Human-readable name of your project | `My Project` | +| `remote_url` | Remote Git repository URL (used for integrations) | `None` (recommended to set) | +| `project_slug` | Directory name for the project | Auto-detected | +| `full_name` | Author name | `Your Name` | +| `license` | License type (`MIT`, `BSD-2`, `GPL-3.0`, `LGPL-3.0`, or none) | `MIT` | +| `github_actions_ci` | Add CI/CD workflows for GitHub Actions | `yes/no` | +| `gitlab_ci` | Add CI/CD workflows for GitLab | `yes/no` | +| `notebooks` | Include Jupyter notebooks for docs and testing | `yes/no` | +| `commandlineinterface` | Add a CLI using `click` | `yes/no` | -* `project_name`: The human-readable name of the project, defaults to `My Project` -* `remote_url`: The remote URL for the newly created repository. This is not only used - to add it as a remote to the Git repository, but also to enable integration with some - services. Defaults to `None` although we strongly advise you to specify it. -* `project_slug`: This will be the name of the generated directory.By default, it is deduced from the specified remote URL and the given project name. -* `full_name`: Author name, defaults to `Your Name` -* `license` adds a license file to the repository. It can be chosen from [MIT](https://opensource.org/licenses/MIT) (default), [BSD-2](https://opensource.org/licenses/BSD-2-Clause), [GPL-3.0](https://opensource.org/licenses/GPL-3.0), [LGPL-3.0](https://opensource.org/licenses/LGPL-3.0) or it can be omitted. -* `github_actions_ci`: Whether to add CI/CD workflows for Github Actions -* `gitlab_ci`: Whether to add a CI workflow for GitLab CI -* `notebooks`: Whether you want to use Jupyter Notebooks for documentation, demonstration - and testing purposes. Will automatically render an example notebook into your Sphinx - documentation and run it during test suite execution. -* `commandlineinterface`: Whether the Package should have a CLI based on `click`. +> Tip: If you use `cookiecutter-python-package` often, you can define your default answers in a `.cookiecutterrc` file in your home directory. +> Learn more in the [Cookiecutter documentation](https://cookiecutter.readthedocs.io/en/latest/advanced/user_config.html). -If you are using `cookiecutter-python-package` a lot, you can customize your default values -by providing a `.cookiecutterrc` file in your home directory, for more details see the -[cookiecutter documentation](https://cookiecutter.readthedocs.io/en/latest/advanced/user_config.html). +--- -# Issues +## Issues & Feedback -Please report any issues you might have with template using [the Github issue -tracker](https://github.com/ssciwr/cookiecutter-python-package) +Found a bug or have a suggestion? +Please open an issue on the [GitHub issue tracker](https://github.com/ssciwr/cookiecutter-python-package).