Getting started¶

1. What is cookiecutter¶

A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.

Visit these links to learn more about cookiecutter:

2. Installation¶

To create a new project from the template you need to install cookiecutter and follow these instructions.

2.1 Requirements¶

A Command-line interface like Git Bash or Terminal.
An IDE like VSCode, Pycharm, Spyder, etc.

2.2 Cookiecutter installation¶

Installing cookiecutter package on Ubuntu or on Windows with Git bash is very easy, you can simply run the next command to install it.

pip install cookiecutter

Visit the link to the cookiecutter documentation to learn more about the installation.

Install cookiecutter in a virtual environment

It is recommended to create a virtual environment and, install the cookiecutter library inside this environment.

2.3 Custom site generation¶

To generate a custom project from the template, follow these steps:

Choose a place to generate the project

Navigate to the path where you desire to generate the project folder.
```
cd /my-projects
```
There is no need to create a specific folder for your project, cookiecutter will create the repository folder for you.
Select the template

Run the cookiecutter command followed by the template repository URL.
```
python -m cookiecutter https://github.com/charlstown/cookie-site.git
```
Customize the template

Fill out the form in the console to customize the template and the project will be generated at the end.

You can accept the default answer in the form by pressing Enter.

You should see a new folder with the repository name you gave as input.
Deploy & test your project locally

Go to your generated project folder, install the requirements and, deploy your project locally by running these commands.
```
cd my-cool-site
pip install -r requirements
python -m mkdocs serve -w overrides/
```

Congrats! You finally generated your own Documentation Site!

2.5 [Optional] Adding the project to a new Github repository¶

Create a new repository in github:

Create the new repository and make sure you name it with the same name of the project folder, in our case my-cool-site.

Warning

Don't add any predefined file from github in the new repository, all the files are included in the local project folder.
Push the local repository:
```
git remote add origin https://github.com/charlstown/my-python-project.git
git branch -M main
git push -u origin main
```
Note

After pushing the project the github action On Push Deploy Documentation will create a new branch called gh-pages. This branch contains the documentation files in html ready to be published in Github Pages.

2.6 [Optional] Deploying the documentation in Github Pages¶

Deploy your documentation in Github pages is so easy, you only need to set the pages configuration pointing at the gh-pages branch generated by our github action On Push Deploy Documentation.

Warning

To deploy the documentation in Github Pages the repository must be a public repository.

Go to the repository settings.
Select Pages at the settings menu under the code and automation section.
Make sure pages is enable and select gh-pages as the site branch under Build and deployment section.
Go to the code and automation section in setting, actions/general.
Make sure you have activate the Read and write permissions in the Workflow permissions section.

Your site should be live at: `https://youruser.github.io/my-cool-site/``

Visit the Set Up section to learn more about the template generation and the input parameters.