Skip to content

Commit

Permalink
docs: improve README (#230)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lsorber
lsorber authored Apr 17, 2024
1 parent 22ec23d commit 7d5ffdc
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 21 deletions.
1 change: 1 addition & 0 deletions .devcontainer/devcontainer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"customizations": {
"vscode": {
"extensions": [
"DavidAnson.vscode-markdownlint",
"ms-python.python",
"tamasfe.even-better-toml",
"visualstudioexptteam.vscodeintellicode"
Expand Down
45 changes: 24 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/radix-ai/poetry-cookiecutter) [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=444870763)

# Poetry Cookiecutter
# 🍪 Poetry Cookiecutter

A modern [Cookiecutter](https://github.com/cookiecutter/cookiecutter) template for scaffolding Python packages and apps.

## 🍿 Demo

See [Conformal Tights](https://github.com/radix-ai/conformal-tights) for an example of a Python package that is scaffolded with this template.

Starting development can be done with a single click by [opening the package in GitHub Codespaces](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=765698489&skip_quickstart=true), or [opening the package in a Dev Container](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/radix-ai/conformal-tights).
See 👖 [Conformal Tights](https://github.com/radix-ai/conformal-tights) for an example of a Python package that is scaffolded with this template. Contributing to this package can be done with a single click by [starting a GitHub Codespace](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=765698489&skip_quickstart=true) or [starting a Dev Container](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/radix-ai/conformal-tights).

## 🎁 Features

Expand All @@ -34,15 +32,20 @@ Starting development can be done with a single click by [opening the package in
To create a new Python project with this template:

1. Install the latest [Cruft](https://github.com/cruft/cruft) and [Cookiecutter](https://github.com/cookiecutter/cookiecutter) in your [Python environment](https://github.com/pyenv/pyenv-virtualenv) with:

```sh
pip install --upgrade "cruft>=2.12.0" "cookiecutter>=2.1.1"
```
2. Create a new repository for your Python project, then clone it locally.

2. [Create a new repository](https://github.com/new) for your Python project, then clone it locally.
3. Run the following command in the parent directory of the cloned repository to apply the Poetry Cookiecutter template:

```sh
cruft create -f https://github.com/radix-ai/poetry-cookiecutter
```

4. _Optional:_ if your repository name differs from your project's slugified name (see `project_name` in the [Template parameters](https://github.com/radix-ai/poetry-cookiecutter#-template-parameters) below), you will need to copy the scaffolded project into the repository with:

```sh
cp -r {project-name}/ {repository-name}/
```
Expand All @@ -56,19 +59,19 @@ To update your Python project with the latest template:

## 🤓 Template parameters

| Parameter | Description |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_type` <br> ["package", "app"] | Whether the project is a publishable Python package or a deployable Python app. |
| `project_name` <br> "Spline Reticulator" | The name of the project. Will be slugified to `snake_case` for importing and `kebab-case` for installing. For example, `My Package` will be `my_package` for importing and `my-package` for installing. |
| `project_description` <br> "A Python package that reticulates splines." | A single-line description of the project. |
| `project_url` <br> "https://github.com/user/spline-reticulator" | The URL to the project's repository. |
| `author_name` <br> "John Smith" | The full name of the primary author of the project. |
| `author_email` <br> "[email protected]" | The email address of the primary author of the project. |
| `python_version` <br> "3.10" | The minimum Python version that the project requires. |
| `development_environment` <br> ["simple", "strict"] | Whether to configure the development environment with a focus on simplicity or with a focus on strictness. In strict mode, additional [Ruff rules](https://beta.ruff.rs/docs/rules/) are added, and tools such as [Mypy](https://github.com/python/mypy) and [Pytest](https://github.com/pytest-dev/pytest) are set to strict mode. |
| `with_conventional_commits` <br> ["0", "1"] | If "1", [Commitizen](https://github.com/commitizen-tools/commitizen) will verify that your commits follow the [Conventional Commits](https://www.conventionalcommits.org/) standard. In return, `cz bump` may be used to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/). |
| `with_fastapi_api` <br> ["0", "1"] | If "1", [FastAPI](https://github.com/tiangolo/fastapi) is added as a run time dependency, FastAPI API stubs and tests are added, a `poe api` command for serving the API is added. |
| `with_typer_cli` <br> ["0", "1"] | If "1", [Typer](https://github.com/tiangolo/typer) is added as a run time dependency, Typer CLI stubs and tests are added, the package itself is registered as a CLI. |
| `continuous_integration` <br> ["GitHub", "GitLab"] | Whether to include a [GitHub Actions](https://docs.github.com/en/actions) or a [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) continuous integration workflow for testing the project, and publishing the package or deploying the app. |
| `private_package_repository_name` <br> "Private Package Repository" | Optional name of a private package repository to install packages from and publish this package to. |
| `private_package_repository_url` <br> "https://pypi.example.com/simple" | Optional URL of a private package repository to install packages from and publish this package to. Make sure to include the `/simple` suffix. For instance, when using a GitLab Package Registry this value should be of the form `https://gitlab.com/api/v4/projects/` `{project_id}` `/packages/pypi/simple`. |
| Parameter | Description |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_type` <br> ["package", "app"] | Whether the project is a publishable Python package or a deployable Python app. |
| `project_name` <br> "Spline Reticulator" | The name of the project. Will be slugified to `snake_case` for importing and `kebab-case` for installing. For example, `My Package` will be `my_package` for importing and `my-package` for installing. |
| `project_description` <br> "A Python package that reticulates splines." | A single-line description of the project. |
| `project_url` <br> "<https://github.com/user/spline-reticulator>" | The URL to the project's repository. |
| `author_name` <br> "John Smith" | The full name of the primary author of the project. |
| `author_email` <br> "<[email protected]>" | The email address of the primary author of the project. |
| `python_version` <br> "3.10" | The minimum Python version that the project requires. |
| `development_environment` <br> ["simple", "strict"] | Whether to configure the development environment with a focus on simplicity or with a focus on strictness. In strict mode, additional [Ruff rules](https://beta.ruff.rs/docs/rules/) are added, and tools such as [Mypy](https://github.com/python/mypy) and [Pytest](https://github.com/pytest-dev/pytest) are set to strict mode. |
| `with_conventional_commits` <br> ["0", "1"] | If "1", [Commitizen](https://github.com/commitizen-tools/commitizen) will verify that your commits follow the [Conventional Commits](https://www.conventionalcommits.org/) standard. In return, `cz bump` may be used to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/). |
| `with_fastapi_api` <br> ["0", "1"] | If "1", [FastAPI](https://github.com/tiangolo/fastapi) is added as a run time dependency, FastAPI API stubs and tests are added, a `poe api` command for serving the API is added. |
| `with_typer_cli` <br> ["0", "1"] | If "1", [Typer](https://github.com/tiangolo/typer) is added as a run time dependency, Typer CLI stubs and tests are added, the package itself is registered as a CLI. |
| `continuous_integration` <br> ["GitHub", "GitLab"] | Whether to include a [GitHub Actions](https://docs.github.com/en/actions) or a [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) continuous integration workflow for testing the project, and publishing the package or deploying the app. |
| `private_package_repository_name` <br> "Private Package Repository" | Optional name of a private package repository to install packages from and publish this package to. |
| `private_package_repository_url` <br> "<https://pypi.example.com/simple>" | Optional URL of a private package repository to install packages from and publish this package to. Make sure to include the `/simple` suffix. For instance, when using a GitLab Package Registry this value should be of the form `https://gitlab.com/api/v4/projects/` `{project_id}` `/packages/pypi/simple`. |

0 comments on commit 7d5ffdc

Please sign in to comment.