py-cookiecutter-templates/README.md

# py-cookiecutter-templates

Project directory structure templates for the Python Cookiecutter package.

# What's Cookiecutter?

The Python package [Cookiecutter](https://github.com/cookiecutter/cookiecutter) assists in creating directory structure for whatever purpose you need such as for example a new Python project, an Ansible role or a `docker-compose` project - anything really that benefits from a unifirm reproducible directory structure. If you've ever wanted to put project structure best practices into version control then Cookiecutter's here to help.

Cookiecutter is governed by so-called Cookiecutter templates, most of its magic inside Cookiecutter templates happens via the [Jinja2 template engine](https://palletsprojects.com/p/jinja/). You'll feel right at home if you're familiar with Ansible.

# Repo layout

Each subdirectory in this repo is a Cookiecutter template, you'll recognize them from their telltale `cookiecutter.json` files. Directories usually also have a readme file explaining more about each individual template.

# Get started

Get Cookiecutter like so:
```
pip install cookiecutter
```

Execute a template like so, `docker-compose` as an example:
```
cookiecutter https://quico.space/Quico/py-cookiecutter-templates.git --directory 'docker-compose'
```

Cookiecutter prompts you for whatever info the template needs then generates files and directories.

This is Cookiecutter prompting for info:
```
project_slug [dir-name]: grafana
service [grafana]:
component_list [grafana]: grafana,nginx
context [ctx]: cncf
```

The end result is a directory structure that has everything you need to hit the ground running.
```
.
└── grafana
    ├── build-context
    │   ├── grafana
    │   │   ├── docker-data
    │   │   │   └── .gitkeep
    │   │   ├── Dockerfile
    │   │   └── extras
    │   │       └── .gitkeep
    │   └── nginx
    │       ├── docker-data
    │       │   └── .gitkeep
    │       ├── Dockerfile
    │       └── extras
    │           └── .gitkeep
    ├── common-settings.yml
    ├── docker-compose.override.yml
    ├── docker-compose.yml
    └── env
        └── fully.qualified.domain.name.example
```

# Developing

To change Cookiecutter templates get yourself an environment then make, test and commit your changes. First things first, the environment.

## Environment

Get yourself a Python virtual environment. In this example we're assuming you're running a Linux operating system and you'll be using [pyenv](https://github.com/pyenv/pyenv) to manage virtual environments.

### pyenv

- Install pyenv with what they are calling their automatic installer. Feel free to also read up on pyenv on their [GitHub project page](https://github.com/pyenv/pyenv).
    ```
    curl https://pyenv.run | bash
    ```

- Following the installer's instruction add at least the following commands to your `~/.bashrc` file
    ```
    export PYENV_ROOT="$HOME/.pyenv"
    command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
    eval "$(pyenv init -)"
    ```

- You will also likely want to add this line which will make sure pyenv auto-activates venvs when you navigate into certain directories. More on that down at [venv](#venv).
    ```
    eval "$(pyenv virtualenv-init -)"
    ```

- Also make sure `~/.bashrc` gets loaded for example by including this in a `~/.bash_profile` file
    ```
    [[ -f ~/.bashrc ]] && . ~/.bashrc
    ```

- Reload `~/.bashrc`
    ```
    source ~/.bashrc
    ```

### Python

- Update pyenv's package list
    ```
    pyenv update
    ```
- Pick a Python version you like, for example copy-paste `3.11.4`:
    ```
    pyenv install --list | less

    ...
    3.10.12
    3.11.0
    3.11-dev
    3.11.1
    3.11.2
    3.11.3
    3.11.4
    3.12.0b2
    3.12-dev
    3.13-dev
    ...
    ```
- Install Python, wait for compilation to finish on your machine
    ```
    pyenv install 3.11.4
    ```

### Repo

- Clone this repo
    ```
    git clone https://quico.space/Quico/py-cookiecutter-templates.git ~/py-cookiecutter-templates
    ```

### venv

- Create a virtual environment where `3.11.4` is the Python version you want to use in this venv and `cookiecutter-3.11.4` is the name of your venv. Adding or dropping the Python version from your venv name comes down to personal preference.
    ```
    pyenv virtualenv 3.11.4 cookiecutter-3.11.4
    ```

- In your repo path `~/py-cookiecutter-templates` create a `.python-version` file to tell pyenv to always activate your desired venv when inside this dir.
    ```
    cd ~/py-cookiecutter-templates
    pyenv local cookiecutter-3.11.4
    ```
    pyenv will immediately prefix your shell's `${PS1}` prompt with the venv name.
    ```
    (cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ 
    ```
    It will deactivate the venv and drop its prefix as soon as you navigate out of this dir.
    ```
    (cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ cd
    [✔ 23:19 user@machine ~]$ 
    ```
    For now though stay in `~/py-cookiecutter-templates`, you're going to want to pip-install [cookiecutter](https://pypi.org/project/cookiecutter).

- Upgrade `pip`
    ```
    pip install --upgrade pip
    ```

- Install [cookiecutter](https://pypi.org/project/cookiecutter)
    ```
    pip install cookiecutter
    ```

All done, your environment is set up.

## Change

Make some code changes, for example to the Docker Compose Cookiecutter template. When you're happy run your local Cookiecutter template to see how your changes are rendering.

- Create `/tmp/cookiecutter-docker-compose`
    ```
    mkdir '/tmp/cookiecutter-docker-compose'
    ```

- Render a Docker Compose directory into your output directory, answer Cookiecutter's prompts:
    ```
    # cookiecutter ~/py-cookiecutter-templates \
        --directory docker-compose \
        --output-dir /tmp/cookiecutter-docker-compose

    project_slug [dir-name]: mydir
    service [mydir]: myservice
    component_list [myservice]: mycomponent_one,mycomponent_two
    context [ctx]: ux_novosibirsk
    ```

- Observe that in `/tmp/cookiecutter-docker-compose` you now have your rendered Docker Compose dir:
    ```
    # tree /tmp/cookiecutter-docker-compose

    /tmp/cookiecutter-docker-compose
    └── mydir
        ├── build-context
        │   ├── mycomponent_one
        │   │   ├── docker-data
        │   │   ├── Dockerfile
        │   │   └── extras
        │   └── mycomponent_two
        │       ├── docker-data
        │       ├── Dockerfile
        │       └── extras
        ├── common-settings.yml
        ├── docker-compose.override.yml
        ├── docker-compose.yml
        └── env
            └── fqdn_context.env.example
    ```

- For rapid testing you will most likely want to not type prompt answers repeatedly. Give them as command line arguments instead, also specify `--no-input` to suppress prompts:
    ```
    cookiecutter ~/py-cookiecutter-templates \
        --no-input \
        --directory docker-compose \
        --output-dir /tmp/cookiecutter-docker-compose \
        project_slug=mydir \
        service=myservice \
        component_list=mycomponent_one,mycomponent_two \
        context=ux_novosibirsk
    ```

## Commit prep

When you're about ready to commit changes into this repo check the following bullet points.

- Did you update the [Cookiecutter template README.md file](docker-compose/README.md), here for example for Docker Compose?
    - Change in behavior?
    - An updated example directory layout?
    - Updated example file content?
- Did you commit a new completely rendered example directory structure into [docker-compose/examples](docker-compose/examples) dir?
- Did you change something that affects existing example directories? If so rerender them.