📝 docs: add dev setup instructions to cookie-doh and template and upd…

…ate readme files

README.md

@@ -5,54 +5,72 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Cookie-doh info
+Cookie-doh is a repository template for creating single Python package projects.
 
-<p align="center">
-:point_right: Short-link: https://aka.ms/cookie-doh
-</p>
+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 <new-repo-folder>
+```
+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
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/{{organization}}/{{project_name}})
+
+[![Open in DevPod!](https://devpod.sh/assets/open-in-devpod.svg)](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,27 +79,49 @@ 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
 
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](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.
 
-[![Open in DevPod!](https://devpod.sh/assets/open-in-devpod.svg)](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.
 
 When you submit a pull request, a CLA bot will automatically determine whether you need to provide
 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 [[email protected]](mailto:[email protected]) with any additional questions or comments.

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 <new-dependencies>  # 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! 🚀

docs/.pages

@@ -1,3 +1,5 @@
 nav:
-- ...
-- reference: api
+  - ...
+  - getting_started.md
+  - dev_setup.md
+  - reference: api

docs/README.md

@@ -0,0 +1 @@
+../README.md

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 <project-folder>
+
+# 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
+```