Skip to content

Revise README for improved clarity and structure #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DragonSenseiGuy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Revise README for improved clarity and structure #47

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 55 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).