Cookiecutter Collabora¶

Welcome to Cookiecutter Collabora, a Cookiecutter template engineered for artificial intelligence, machine learning, and generative AI projects. This template isn't just a starting point; it's a comprehensive framework designed to guide you through the intricacies of AI project development. It combines best practices, industry standards, and a suite of tools that aligns with the dynamic needs of modern AI development.

Prerequisites¶

Development Environment:¶

Visual Studio Code (VS Code) desktop
AWS Cloud Code Editor
GitHub Codespaces
Any other cloud-powered development environment compatible with VS Code or VS Code Open Source

Python:¶

Ensure Python is installed on your system. This project is compatible with Python 3.x.

Usage¶

Installing Cookiecutter¶

Before starting, ensure Cookiecutter is installed on your system:

pip install cookiecutter

Generate a New Project¶

Create a new project by running:

cookiecutter git@github.com:markeyser/cookiecutter-collabora.git

You will be prompted to enter details for your project, such as project name, OS type, author name, and more. For example:

  [1/9] project_name (Project Name): My AI Project
  [2/9] project_slug (my-ai-project):
  [3/9] package_name (myaiproject):
  [4/9] environment_name (my-ai-project-env):
  [5/9] author_name (Your name or your organization/company/team): Jane Doe
  [6/9] author_email (youremail@example.com): jane.doe@example.com
  [7/9] description (A short description of the project.): AI project development
  [8/9] independent_reviewer (github_username_of_independent_reviewer):
  [9/9] site_name (My AI Project Docs):
INFO:root:Current working directory: /Users/username/Projects/my-ai-project

This process will generate a new project with your specific configurations.

This will create a new project based on the cookiecutter-collabora template with your specified details.

cd my-ai-project

Once you're in your project's directory, you can open the entire directory in Visual Studio Code:

code .

Resulting Directory Structure¶

The directory structure of your new project looks like this:

├── .devcontainer                  <- Directory for Visual Studio Code Dev Container configuration.
│   └── devcontainer.json          <- Configuration file for defining the development container.
├── .github                        <- Directory for GitHub-specific configuration and metadata.
│   ├── CODEOWNERS                 <- File to define code owners for the repository.
│   ├── CONTRIBUTING.md            <- Guidelines for contributing to the project.
│   └── pull_request_template.md.  <- Template for pull requests to standardize and improve PR quality.
├── .vscode                        <- Directory for Visual Studio Code-specific configuration files.
│   ├── cspell.json                <- Configuration file for the Code Spell Checker extension.
│   ├── dictionaries               <- Directory for custom dictionary files.
│   │   └── data-science-en.txt    <- Custom dictionary for data science terminology.
│   ├── extensions.json            <- Recommended extensions for the project.
│   └── settings.json              <- Workspace-specific settings for Visual Studio Code.
├── config                         <- Configuration files for the project.
├── data                           <- Data for the project, divided into different stages of data processing.
│   ├── raw                        <- Original, immutable data dump.
│   ├── external                   <- Data from third-party sources.
│   ├── interim                    <- Intermediate data, partially processed.
│   ├── processed                  <- Fully processed data, ready for analysis.
│   └── features                   <- Engineered features ready for model training.
├── docs                           <- Documentation for the project.
│   ├── api-reference.md           <- API reference documentation.
│   ├── explanation.md             <- Detailed explanations and conceptual documentation.
│   ├── how-to-guides.md           <- Step-by-step guides on performing common tasks.
│   ├── index.md                   <- The main documentation index page.
│   └── tutorials.md               <- Tutorials related to the project.
├── log                            <- Logs generated by the project.
├── models                         <- Machine learning models, scripts, and other related artifacts.
├── notebooks                      <- Jupyter notebooks for experiments, examples, or data analysis.
├── scripts                        <- Directory for project-specific scripts and utilities.
│   └── hooks                      <- Directory for custom git hooks and other automation scripts.
│       ├── branch-name-check.sh   <- Hook script for checking branch names.
│       ├── commit-msg-check.sh    <- Hook script for checking commit messages.
│       ├── filename-check.sh      <- Hook script for checking file names.
│       ├── generate_docs.sh       <- Script for generating documentation.
│       └── restricted-file-check.sh   <- Hook script for checking restricted files.
├── src                            <- Source code for the project.
│   └── {{cookiecutter.package_name}}  <- Main project module.
│       ├── __init__.py            <- Initializes the Python package.
│       ├── main.py                <- Entry point for the application.
│       ├── app.py                 <- Main application logic.
│       └── utils.py               <- Utility functions.
├── tests                          <- Directory for all project tests.
│   ├── integration                <- Integration tests.
│   └── spec                       <- Specification tests (unit tests).
├── .gitignore                     <- Specifies intentionally untracked files to ignore.
├── .pre-commit-config.yaml        <- Configuration for pre-commit hooks.
├── Dockerfile                     <- Dockerfile for containerizing the application.
├── Makefile                       <- Makefile with commands like `make data` or `make train`.
├── mkdocs.yml                     <- Configuration file for MkDocs, a static site generator for project documentation.
├── pyproject.toml                 <- Configuration file for Python projects which includes dependencies and package information.
├── README.md                      <- The top-level README for developers using this project.
└── .env                           <- Environment variables configuration file (not visible).

Generate a Project from a Downloaded Template¶

If you have already downloaded the Cookiecutter template:

Listing Installed Cookiecutter Templates¶

To see installed Cookiecutter templates, use:

cookiecutter --list-installed
1 installed templates:
 * cookiecutter-collabora

Locating the `.cookiecutters` Directory on a Mac¶

Your cloned cookiecutters are usually stored in ~/.cookiecutters/.

Open Terminal: Find Terminal in Applications > Utilities, or use Spotlight.
Navigate to Home Directory: Type cd ~ and press Enter.
List Hidden Directories: Use ls -a to view all files and directories, including hidden ones like .cookiecutters.
Access the .cookiecutters Directory: Enter cd .cookiecutters.
View Template Contents (Optional): Use ls to view the templates in the .cookiecutters directory.

pwd
/Users/username/.cookiecutters/cookiecutter-collabora

Creating a New Project with a Template¶

To create a project using the cookiecutter-collabora template:

cookiecutter /Users/username/.cookiecutters/cookiecutter-collabora

Enter the details for your project when prompted. For instance:

  [1/9] project_name (Project Name): My AI Project
  [2/9] project_slug (my-ai-project):
  [3/9] package_name (myaiproject):
  [4/9] environment_name (my-ai-project-env):
  [5/9] author_name (Your name or your organization/company/team): Jane Doe
  [6/9] author_email (youremail@example.com): jane.doe@example.com
  [7/9] description (A short description of the project.): AI project development
  [8/9] independent_reviewer (github_username_of_independent_reviewer):
  [9/9] site_name (My AI Project Docs):
INFO:root:Current working directory: /Users/username/Projects/my-ai-project