Add documentation for getting started

[goatsweater]

The existing project documentation doesn't cover getting started with the cookiecutter, and assumes the presence of certain required software (cookiecutter, for instance). In a similar vein to how the UK provides a getting started guide, there needs to be one for users of this as well.

Since we're using conda as the base package it isn't clear if required software should be in a requirements file for pip or a conda environment specification.

Known required packages:

• cookiecutter
• pre-commit

[asolis]

I was using only cruft based on your suggestion. It's the only extra package necessary to create a new project and recreate the new development environment. It's simpler because it allows to create the new project and update the project if the template was modified.

required packages:

• cruft

workflow:

• cruft create https://github.com/StatCan/datascience-cookiecutter.git
• cd [[repo_name]]
• git init .
• git add -A (i.e., .cruft.json becomes part of your project intentionally)
• git commit -m "Initial commit"
• git add remote url [your_repo_url]
• git push --up-stream origin master
• conda env create -f environment.yml The environment contains all the necessary tools to work with the template such as: pre-commit, flake8, black, ...
• conda activate [[your-proj-env]]

Check status of your project against template

• cruft check
• cruft diff

Update your project from template:

• cruft update

Cons:

cruft is only compatible with cookiecutter version > 1.6 and < 2.0. It might not work if you cookiecutter template uses new functionalities from version 2.xx . At this point the datascience-cookiecutter uses none of those features.

[asolis]

I didn't find a comprehensive workflow using the cookiecutter CLI. Except for creation, common tasks such as updating your project from template and checking differences with upstream are not specified in their doc. I couldn't identify workflow steps from their documentation (The docs seems directed on how to create template projects, not so much on CLI usage)

[ToucheSir]

Reading https://cookiecutter.readthedocs.io/en/2.1.0/cli_options.html, it appears cookiecutter only supports template instantiation? If Cruft subsumes that functionality, that's a great argument for using it instead.

[asolis]

FYI, I started this this: https://gitlab.com/dsd4/hydra/hydra-module-template/-/wikis/Getting-Started. It might be similar to what you would like to do.

[goatsweater]

Using the work done by @asolis as a starting point, I've begun writing a getting started guide on 33-getting-started-docs. It will continue to be refined as we work toward publication of the project, but liked won't be merged until after publication.