diff --git a/README.md b/README.md
index 7d2032b..8c2f74b 100644
--- a/README.md
+++ b/README.md
@@ -5,54 +5,72 @@
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
-Cookie-doh info
+Cookie-doh is a repository template for creating single Python package projects.
-
-:point_right: Short-link: https://aka.ms/cookie-doh
-
+It includes [Poetry](https://python-poetry.org/) for dependency management,
+[ruff](https://github.com/astral-sh/ruff) for formatting and linting,
+[pyright](https://github.com/microsoft/pyright) for annotations,
+and GitHub Actions for [CI](https://en.wikipedia.org/wiki/Continuous_integration).
+
+Optionally, you can enable documentation builds with
+[MkDocs](https://squidfunk.github.io/mkdocs-material/),
+[pre-commit](https://pre-commit.com/) for quick code fixes, and
+[commitizen](https://commitizen-tools.github.io/commitizen/)
+for writing [conventional commits](https://www.conventionalcommits.org/).
+
+
+:point_right: Short-link: [https://aka.ms/cookie-doh]()
-----------------------------------------------------------------
-## :notebook_with_decorative_cover: Documentation
-https://microsoft.github.io/cookie-doh
+## :rocket: Getting Started with cookie-doh
+This template uses [_copier_](https://github.com/copier-org/copier) to create new repositories.
+If you don't have _copier_, follow the [installation instructions](https://copier.readthedocs.io/en/stable/#installation).
-## :floppy_disk: Source Code
-https://github.com/microsoft/cookie-doh
+Then, simply type
+```bash
+copier copy gh:microsoft/cookie-doh
+```
+and answer the questions to create your new project.
-## :rocket: Getting Started
+If cookie-doh tags a new version that includes new changes, you can merge those changes
+into your project by changing directory into your repo and running:
+```bash
+copier update
+```
+This will update your project with the latest changes from cookie-doh :cookie:.
-### Optional system dependencies
+## :notebook_with_decorative_cover: Documentation
-We use the following optional dependencies for development:
+Visit the documentation:
-* [direnv](https://direnv.net/): To manage environment variables and load python virtual environments automatically.
-* [pyenv](https://github.com/pyenv/pyenv): To manage python versions.
-* [pipx](https://pipxproject.github.io/pipx/): To install python packages in isolated environments.
-{% if commitizen -%}
-* [commitizen](https://commitizen-tools.github.io/commitizen/): To help with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
-* [cz-conventional-gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji): A commitizen plugin that combines gitmoji and conventional commits.
-{%- endif %}
-{% if precommit -%}
-* [pre-commit](https://pre-commit.com/): To run code formatting and linting before committing.
-{%- endif %}
+https://microsoft.github.io/cookie-doh
-### Required system dependencies
+Go to [getting started with your new repo](https://microsoft.github.io/cookie-doh/getting_started)
+to understand the structure of your new project and how to configure it further.
-* [poetry](https://python-poetry.org/): To manage package dependencies and virtual environments.
-* [python >= 3.10](https://www.python.org/)
-For setting up the development environment:
+## :space_invader: Codespaces
-* Clone the repository and cd into it.
-* Install the dependencies with poetry:
-```bash
-poetry install
-```
+We provide a configured devcontainer setup for you to use in in your new project and/or cookie-doh itself.
+You can use it to create a container image with all the necessary dependencies automatically,
+and use in a remote development environment with GitHub Codespaces or DevPod.
+
+Learn about [GitHub Codespaces](https://docs.github.com/en/codespaces) and/or [DevPod](https://devpod.sh/),
+and click below to clone or fork this repository automatically and start developing:
-### Devcontainer
+[](https://codespaces.new/{{organization}}/{{project_name}})
+
+[](https://devpod.sh/open#https://github.com/{{organization}}/{{project_name}})
+
+
+## :gear: Devcontainer
+
+Alternatively, you can you can build a local container directly and use it in VSCode and/or
+PyCharm without developing in a remote node or setting up a local environment.
Learn about [Devcontainers](https://containers.dev/).
Requires [Docker](https://www.docker.com/get-started/) installed on your local machine.
@@ -61,20 +79,40 @@ Requires [Docker](https://www.docker.com/get-started/) installed on your local m
and/or [PyCharm](https://www.jetbrains.com/help/pycharm/connect-to-devcontainer.html).
-### Codespaces
+## :computer: Local Development
-Learn about [GitHub Codespaces](https://docs.github.com/en/codespaces) and/or [DevPod](https://devpod.sh/).
+### Required system dependencies
-[](https://codespaces.new/{{organization}}/{{project_name}})
+* [python >= 3.10](https://www.python.org/)
+* [poetry](https://python-poetry.org/): To manage package dependencies and virtual environments.
-[](https://devpod.sh/open#https://github.com/{{organization}}/{{project_name}})
+For setting up the development environment (both for your newly created project and cookie-doh)
+* cd into your repo.
+* Install the project dependencies with poetry:
+```bash
+poetry install
+```
+
+### Optional development setup
+
+We use the following (optional) dependencies for development.
+If you are going to set up a local development environment for your created project, or for cookie-doh
+itself, follow the local development setup [instructions](https://microsoft.github.io/cookie-doh/dev_setup).
+
+* [direnv](https://direnv.net/): To load python virtual environments automatically and manage environment variables.
+* [pyenv](https://github.com/pyenv/pyenv): To manage python versions.
+* [pipx](https://pipxproject.github.io/pipx/): To install python packages in isolated environments.
+* [commitizen](https://commitizen-tools.github.io/commitizen/): To help with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+* [cz-conventional-gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji): A commitizen plugin that combines [gitmoji](https://gitmoji.dev/) and conventional commits.
+* [pre-commit](https://pre-commit.com/): To run code formatting and linting before committing.
+* [copier](https://copier.readthedocs.io/en/stable/): To create new repositories from this template
+and update them with new changes.
---------------------------------------------
## :mountain: Contributing
-This project welcomes contributions and suggestions. Most contributions require you to agree to a
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
@@ -82,6 +120,8 @@ When you submit a pull request, a CLA bot will automatically determine whether y
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.
+You may also fork this project, modify it and create your own template from it and share with others.
+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
diff --git a/copier.yml b/copier.yml
index 18d3485..dce7740 100644
--- a/copier.yml
+++ b/copier.yml
@@ -84,17 +84,19 @@ _message_after_copy: |
Next steps:
- {% if repo_exists -%}
-
- 1. Pull repository into your newly created project:
+ 1. Change directory and initialize GitHub:
$ cd {{ _copier_conf.dst_path }}
$ git init
+
+ {% if repo_exists -%}
+ 2. Pull repository into your newly created project:
+
$ git remote add origin https://github.com/{{ organization }}/{{ project_name }}.git
$ git pull origin main # and resolve any conflicts
{% else -%}
- 1. Create a new repository on GitHub:
+ 2. Create a new repository on GitHub:
a. Install the GitHub CLI (if you haven't already): https://cli.github.com/
b. Authenticate with GitHub and create the new repository:
@@ -105,15 +107,17 @@ _message_after_copy: |
{% endif -%}
- 2. Add project dependencies to `pyproject.toml` and install them with Poetry:
+ 3. Add project dependencies to `pyproject.toml` and install them with Poetry:
$ poetry add # optional
$ poetry install
- 3. Add the project outputs, configure pre-commit and commit your changes:
+ 4. Add the project outputs, configure pre-commit and commit your changes:
$ git add .
+ {% if precommit -%}
$ pre-commit install --install-hooks
+ {% endif -%}
$ git commit -m "init: initialize repo"
5. Happy coding! 🚀
diff --git a/docs/.pages b/docs/.pages
index a6123b3..e5055aa 100644
--- a/docs/.pages
+++ b/docs/.pages
@@ -1,3 +1,5 @@
nav:
-- ...
-- reference: api
+ - ...
+ - getting_started.md
+ - dev_setup.md
+ - reference: api
diff --git a/docs/README.md b/docs/README.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/docs/dev_setup.md b/docs/dev_setup.md
new file mode 100644
index 0000000..b749806
--- /dev/null
+++ b/docs/dev_setup.md
@@ -0,0 +1,121 @@
+# :computer: local dev setup
+
+ If you use [codespaces](index.md#-codespaces) or [devcontainers](index.md#️-devcontainer),
+ you don't need to set up a local development environment.
+ But otherwise, follow these steps to set up some useful utilities
+
+## :penguin: Linux/WSL instructions
+
+
+### [Direnv](https://direnv.net/)
+
+To load python virtual environments automatically and manage environment variables.
+
+```bash
+# Enter project
+cd
+
+# Install direnv
+sudo apt update && sudo apt install direnv
+
+# Add direnv to your shell
+echo 'eval "$(direnv hook bash)"' >> ~/.bashrc # if you use bash
+echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc # if you use zsh
+eval "$(direnv hook bash)" # add to current shell
+
+# Add poetry support to direnv
+mkdir -p ~/.config/direnv/
+cp .devcontainer/direnvrc ~/.config/direnv/direnvrc
+```
+
+
+### [Pyenv](https://github.com/pyenv/pyenv)
+
+For installing and managing (multiple) python versions.
+You may want to use the system's version and not install pyenv.
+
+Otherwise, follow these instructions.
+
+1. [Install Python build dependencies](https://github.com/pyenv/pyenv?tab=readme-ov-file#install-python-build-dependencies):
+ ```bash
+ sudo apt update && sudo apt curl install build-essential libssl-dev zlib1g-dev \
+ libbz2-dev libreadline-dev libsqlite3-dev curl \
+ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
+ ```
+2. [Install pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#automatic-installer)
+ ```bash
+ curl https://pyenv.run | bash
+ ```
+
+3. [Set up your shell environment for Pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#set-up-your-shell-environment-for-pyenv)
+ ```bash
+ # add env variables to your bash .profile (if you use bash)
+ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
+ echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
+ echo 'eval "$(pyenv init --path)"' >> ~/.profile
+
+ # add shell integration to bash shell
+ echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+
+ # add env variables to zsh's .zprofile (if you use zsh)
+ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
+ echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
+ echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
+
+ # add shell integration to zsh shell
+ echo 'eval "$(pyenv init -)"' >> ~/.zshrc
+ ```
+
+4. [Install python versions](https://github.com/pyenv/pyenv?tab=readme-ov-file#install-additional-python-versions)
+ ```bash
+ pyenv install 3.10
+ pyenv global 3.10
+ ```
+
+
+### [Pipx](https://pipxproject.github.io/pipx/)
+
+For installing python packages in isolated environments.
+
+```bash
+sudo apt update && sudo apt install pipx
+pipx ensurepath
+```
+
+
+### [Poetry](https://python-poetry.org/)
+To manage package dependencies and virtual environments.
+
+```bash
+pipx install poetry
+```
+
+
+### [Pre-commit](https://pre-commit.com/)
+To run code formatting and linting before committing.
+
+```bash
+pipx install pre-commit
+```
+
+In your projects, you should enable pre-commit hooks by running:
+```bash
+pre-commit install --install-hooks
+```
+
+
+### [Commitizen](https://commitizen-tools.github.io/commitizen/)
+To help with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+```bash
+pipx install commitizen
+pipx inject commitizen cz-conventional-gitmoji # installs emoji plugin
+```
+
+
+### [Copier](https://copier.readthedocs.io/en/stable/)
+To create new repositories from [cookie-doh](https://aka.ms/cookie-doh).
+
+```bash
+pipx install copier
+```
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 0000000..d1dc424
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,153 @@
+# :rocket: new project
+
+## :tada: Create a new project
+
+1. [Install copier](dev_setup#copier).
+2. Create a new project from the template:
+ ```bash
+ copier gh:microsoft/cookie-doh
+ ```
+
+
+## :walking: First steps with the new project
+Once you've created your new repository, the creation process will tell you to:
+
+1. Change directory and initialize git:
+ ```bash
+ cd
+ git init
+ ```
+2. Configure upstream / remote repository:
+
+ a. if you have an existing repository:
+ ```bash
+ git remote add origin https://github.com/{{organization}}/{{project_name}}.git
+ git pull origin main # and resolve any conflicts
+ ```
+ b. or, create a new repository (install [GitHub CLI](https://cli.github.com/) if necessary)
+ ```bash
+ gh auth login
+ gh repo create {{organization}}/{{project_name}} --private --remote=origin
+ ```
+3. Install dependencies:
+ ```bash
+ poetry add
+ poetry install
+ ```
+4. Commit the initial files:
+ ```bash
+ git add .
+ pre-commit install --install-hooks # only if you chose to get pre-commit in your project
+ git commit -m "init: initialize repo"
+ git push -u origin main
+ ```
+5. Happy coding! :rocket:
+
+
+## :feather: Update your project
+
+In the future you can keep track of the latest changes of
+[cookie-doh](https://aka.ms/cookie-doh) by running:
+```bash
+copier update
+```
+Get more options with `copier --help` and/or `copier update --help`.
+
+
+## :house_with_garden: Project description
+
+### :bricks: Main structure
+Your new repo will have the following structure:
+
+```
+/docs # only if you enabled documentation builds
+ ├── index.md
+ └── .pages
+/src/{{project_name}}
+ ├── __init__.py
+ └── example.py
+/test/test_{{project_name}}
+ ├── __init__.py
+ └── test_example.py
+pyproject.toml
+README.md
+```
+
+* If you use VSCode, load your project as a
+[workspace](https://code.visualstudio.com/docs/editor/workspaces#_singlefolder-workspaces)
+by opening your project's folder.
+This will set up VSCode with convenient settings and recommended extensions.
+* Put your python code in `src/{{project_name}}`, tests in `test/test_{{project_name}}`,
+and markdown documentation in `docs`.
+* When you run `poetry install` it will install the `src` package in editable mode, so every package
+and module you add will be available to import locally in your project.
+* Add new dependencies to `pyproject.toml` and run `poetry install` to install them or
+run `poetry add ` to add a new dependency. Run `poetry update` to update all dependencies.
+Poetry will create a `.venv` folder with a virtual environment inside your project (configurable
+with `poetry.toml`).
+* To run tests, use `poetry run pytest`, or if you use [_direnv_](https://github.com/direnv/direnv)
+and have enabled it, simply run `pytest`. See setting up your development environment below.
+* You will only get the `docs` folder if you enabled documentation builds in the _copier_ prompts.
+Add your markdown documentation to the `docs` folder and run `bin/serve-docs` to see a live preview
+(or `serve-docs` if you use _direnv_). Make changes to `.pages` to edit your navigation pane.
+* Edit your `README.md` file to include information about your project, how to install it,
+how to use it, and any other relevant information you may want to share.
+
+
+### :building_construction: Configuration, commands and workflows
+
+Further relevant configuration files, binaries and workflows are shown in the following tree:
+```
+ruff.toml
+pyrightconfig.json
+.codespellrc
+/bin
+/.github
+ ├── dependabot.yml
+ └── workflows
+ ├── main.yml
+ ├── pr.yml
+ └── weekly.yml
+.envrc
+```
+
+* The `ruff.toml` file is used by _ruff_ to configure code formatting and linting rules, including
+black, isort, flake8, and others. Use this file to configure your code style and linting rules
+and exceptions. It runs fast and it is integrated in VSCode with the _ruff_ extension.
+* The `pyrightconfig.json` file is used by _pyright_ to configure type checking rules and exceptions.
+You can add exceptions to the `pyrightconfig.json` file to suppress warnings or errors.
+We encourage you to use type annotations in your code to help detect errors early, but most
+importantly, to improve readability of your code (to your future self and others).
+* The `.codespellrc` file is used by _codespell_ to check spelling in your files and code.
+If _codespell_ detects spelling errors, it will suggest corrections.
+You can add exceptions to the `.codespellrc` file.
+* The `bin` folder includes scripts to help you with common tasks. For example `bin/check-all` will
+run all checks including `pre-commit`, `ruff`, `pytest`, `pyright` and `mkdocs` (if enabled).
+You should run this check prior to committing changes to your repository or pushing to your remote.
+* The `.github` folder includes `.dependabot.yml` for automated dependency updates in GitHub,
+and workflows folder for automatic CI checks on pull requests, pushes, and weekly scheduled tasks.
+* The `.envrc` file is used by _direnv_ to manage environment variables and load python virtual
+environments automatically. We strongly encourage you to use _direnv_ to manage your [development
+environment](dev_setup.md#direnv) for its convenience.
+
+
+### :cherries: Pre-commit, commitizen and documentation (optional)
+
+Other configuration files may include (depending on your choices during the _copier_ process):
+```
+.pre-commit-config.yaml
+.cz.toml
+mkdocs.yml
+.apidoc_conf.py
+```
+
+* Pre-commit is a tool to run code formatting and linting before committing changes.
+You can run `pre-commit run --all-files` to run a bunch of checks manually.
+Add new hooks or remove existing ones in the `.pre-commit-config.yaml` file.
+* The `.cz.toml` file is used by _commitizen_ to write commit message.
+It relies on the `cz-conventional-gitmoji` plugin to combine gitmoji and conventional commits.
+Write a commit as `fix: correct typo in README` or `feat: add new feature` and `pre-commit` will
+prepend a corresponding gitmoji to your commit message.
+Run `cz commit` to write a commit message interactively listing all possible types and options.
+* Finally, the `mkdocs.yml` and `.apidoc_conf.py` file are used by _mkdocs_ and _sphinx_ to
+configure your documentation build and API reference docstrings.
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index a59b378..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1 +0,0 @@
-# :cookie: cookie-doh
diff --git a/docs/index.md b/docs/index.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/docs/index.md.jinja b/docs/index.md.jinja
deleted file mode 100644
index af56f9a..0000000
--- a/docs/index.md.jinja
+++ /dev/null
@@ -1 +0,0 @@
-# :sparkles: {{project_name}}
diff --git a/template/README.md.jinja b/template/README.md.jinja
index c485ffb..577c426 100644
--- a/template/README.md.jinja
+++ b/template/README.md.jinja
@@ -5,9 +5,10 @@
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
------------------------------------------------------------------
-{{ project_name }} info
+
+
+-----------------------------------------------------------------
{% if documentation -%}
## :notebook_with_decorative_cover: Documentation
@@ -17,31 +18,30 @@ https://{{ organization }}.github.io/{{ project_name }}
https://github.com/{{ organization }}/{{ project_name }}
{%- endif -%}
-### Optional system dependencies
-We use the following optional dependencies for development:
+## :rocket: Getting Started with {{ project_name }}
-* [direnv](https://direnv.net/): To manage environment variables and load python virtual environments automatically.
-* [pyenv](https://github.com/pyenv/pyenv): To manage python versions.
-* [pipx](https://pipxproject.github.io/pipx/): To install python packages in isolated environments.
-* [commitizen](https://commitizen-tools.github.io/commitizen/): To help with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
-* [cz-conventional-gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji): A commitizen plugin that combines gitmoji and conventional commits.
-* [pre-commit](https://pre-commit.com/): To run code formatting and linting before committing.
+
-### Required system dependencies
-* [poetry](https://python-poetry.org/): To manage package dependencies and virtual environments.
-* [python >= 3.10](https://www.python.org/)
+## :space_invader: Codespaces
-For setting up the development environment:
+We provide a configured devcontainer setup for you to use in in your new project and/or cookie-doh itself.
+You can use it to create a container image with all the necessary dependencies automatically,
+and use in a remote development environment with GitHub Codespaces or DevPod.
-* Clone the repository and cd into it.
-* Install the dependencies with poetry:
-```bash
-poetry install
-```
+Learn about [GitHub Codespaces](https://docs.github.com/en/codespaces) and/or [DevPod](https://devpod.sh/),
+and click below to clone or fork this repository automatically and start developing:
+
+[](https://codespaces.new/{{organization}}/{{project_name}})
+
+[](https://devpod.sh/open#https://github.com/{{organization}}/{{project_name}})
-### Devcontainer
+
+## :gear: Devcontainer
+
+Alternatively, you can you can build a local container directly and use it in VSCode and/or
+PyCharm without developing in a remote node or setting up a local environment.
Learn about [Devcontainers](https://containers.dev/).
Requires [Docker](https://www.docker.com/get-started/) installed on your local machine.
@@ -50,15 +50,35 @@ Requires [Docker](https://www.docker.com/get-started/) installed on your local m
and/or [PyCharm](https://www.jetbrains.com/help/pycharm/connect-to-devcontainer.html).
-### Codespaces
+## :computer: Local Development
+
+### Required system dependencies
+
+* [python >= 3.10](https://www.python.org/)
+* [poetry](https://python-poetry.org/): To manage package dependencies and virtual environments.
-Learn about [GitHub Codespaces](https://docs.github.com/en/codespaces) and/or [DevPod](https://devpod.sh/).
+For setting up the development environment (both for your newly created project and cookie-doh)
-[](https://codespaces.new/{{ organization }}/{{ project_name }})
+* cd into your repo.
+* Install the project dependencies with poetry:
+```bash
+poetry install
+```
-[](https://devpod.sh/open#https://github.com/{{ organization }}/{{ project_name }})
+### Optional development setup
+We use the following (optional) dependencies for development.
+If you are going to set up a local development environment for your created project, or for cookie-doh
+itself, follow the local development setup [instructions](https://microsoft.github.io/cookie-doh/dev_setup).
+* [direnv](https://direnv.net/): To load python virtual environments automatically and manage environment variables.
+* [pyenv](https://github.com/pyenv/pyenv): To manage python versions.
+* [pipx](https://pipxproject.github.io/pipx/): To install python packages in isolated environments.
+* [commitizen](https://commitizen-tools.github.io/commitizen/): To help with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+* [cz-conventional-gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji): A commitizen plugin that combines [gitmoji](https://gitmoji.dev/) and conventional commits.
+* [pre-commit](https://pre-commit.com/): To run code formatting and linting before committing.
+* [copier](https://copier.readthedocs.io/en/stable/): To create new repositories from this template
+and update them with new changes.
{% if organization == 'microsoft' %}