Update documentation (#28)

* chore: `invoke bake` and documentation

* fix: Tests

.gitignore

@@ -127,3 +127,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+/outputs/

README.md

@@ -24,8 +24,172 @@ Run all tests:
 invoke tests
 ```
 
-List all available tasks
+List all available tasks:
 
 ```shell
 invoke help
 ```
+
+Bake a cookie:
+
+```shell
+invoke bake --template=nautobot-app
+```
+
+## Usage with Docker and Invoke
+
+To use templates locally with Docker and Invoke, you need first set up the repository as explained in [local quick-start](#local-quickstart).
+
+Then, you can use the following commands:
+
+```shell
+invoke bake
+```
+
+Output:
+
+```shell
+docker compose run --rm -- dev cookiecutter --output-dir=./outputs   ./nautobot-app
+  [1/18] codeowner_github_usernames (@smith-ntc): 
+  [2/18] full_name (Network to Code, LLC): 
+  [3/18] email ([email protected]): 
+  [4/18] github_org (nautobot): 
+  [5/18] plugin_name (my_plugin): 
+  [6/18] verbose_name (My Plugin): 
+  [7/18] plugin_slug (my-plugin): 
+  [8/18] project_slug (nautobot-plugin-my-plugin): 
+  [9/18] repo_url (https://github.com/nautobot/nautobot-plugin-my-plugin): 
+  [10/18] base_url (my-plugin): 
+  [11/18] min_nautobot_version (1.6.0): 
+  [12/18] max_nautobot_version (1.9999): 
+  [13/18] camel_name (MyPlugin): 
+  [14/18] project_short_description (My Plugin): 
+  [15/18] model_class_name (None): 
+  [16/18] Select open_source_license
+    1 - Apache-2.0
+    2 - Not open source
+    Choose from [1/2] (1): 
+  [17/18] docs_base_url (https://docs.nautobot.com): 
+  [18/18] docs_app_url (https://docs.nautobot.com/projects/my-plugin/en/latest): 
+
+Congratulations! Your cookie has now been baked. It is located at /opt/ntc/nautobot/cookiecutter-nautobot-app/outputs/nautobot-plugin-my-plugin.
+
+⚠️⚠️ Before you start using your cookie you must run the following commands inside your cookie:
+
+* poetry lock
+* cp development/creds.example.env development/creds.env
+* poetry shell
+* invoke makemigrations
+
+The file `creds.env` will be ignored by git and can be used to override default environment variables.
+```
+
+This command, bakes a new cookie using the `nautobot-app` template into `outputs` directory.
+
+### Help
+
+To see all arguments run:
+
+```shell
+invoke bake --help
+```
+
+Output:
+
+```shell
+Usage: inv[oke] [--core-opts] bake [--options] [other tasks here ...]
+
+Docstring:
+  Bake a new cookie from the template.
+
+Options:
+  -d, --debug                      Whether to run in debug mode (defaults to False)
+  -i, --[no-]input                 Whether to require user input, ignored with `--json-file` (defaults to True)
+  -j STRING, --json-file=STRING    Path to a JSON file containing answers to prompts (defaults to empty)
+  -o STRING, --output-dir=STRING   Path to the output directory (defaults to ./outputs)
+  -t STRING, --template=STRING     Path to the cookiecutter template to bake (defaults to ./nautobot-app)
+```
+
+!!! IMPORTANT !!! The `--output-dir` argument should be located in the current directory, as the Cookiecutter creates the cookie inside the Docker container with the current directory bind mounted. When baking somewhere else, the resulting cookie would not be available from calling host system.
+
+### JSON file
+
+You can reuse existing JSON file with pre-filled template prompts. To do so, you need to pass the path to the JSON file using the `--json-file` argument.
+
+When running the command with `--json-file` argument, the command will not prompt for any input.
+
+First create the `my-app.json` file:
+
+```json
+{
+    "cookiecutter": {
+        "codeowner_github_usernames": "@smith-ntc",
+        "full_name": "Network to Code, LLC",
+        "email": "[email protected]",
+        "github_org": "nautobot",
+        "plugin_name": "my_app",
+        "verbose_name": "My App",
+        "plugin_slug": "my-app",
+        "project_slug": "nautobot-plugin-my-app",
+        "repo_url": "https://github.com/nautobot/nautobot-plugin-my-app",
+        "base_url": "my-app",
+        "min_nautobot_version": "2.0.0",
+        "max_nautobot_version": "2.9999",
+        "camel_name": "MyApp",
+        "project_short_description": "My App",
+        "model_class_name": "MyModel",
+        "open_source_license": "Apache-2.0",
+        "docs_base_url": "https://docs.nautobot.com",
+        "docs_app_url": "https://docs.nautobot.com/projects/my-app/en/latest"
+    }
+}
+```
+
+Then run the following command:
+
+```shell
+invoke bake --json-file=my-app.json
+```
+
+Output:
+
+```shell
+docker compose run --rm -- dev cookiecutter --output-dir=./outputs  --replay-file=my-app.json ./nautobot-app
+
+Congratulations! Your cookie has now been baked. It is located at /opt/ntc/nautobot/cookiecutter-nautobot-app/outputs/nautobot-plugin-my-app.
+
+⚠️⚠️ Before you start using your cookie you must run the following commands inside your cookie:
+
+* poetry lock
+* cp development/creds.example.env development/creds.env
+* poetry shell
+* invoke makemigrations
+
+The file `creds.env` will be ignored by git and can be used to override default environment variables.
+```
+
+## Usage with Cookiecutter
+
+It's possible to use Cookiecutter directly without installing templates locally. To do so, set up your environment first.
+
+Pre-requisites:
+
+- Python with pip.
+
+```shell
+pip install cookiecutter
+mkdir outpus
+```
+
+Then run the following commands:
+
+```shell
+cookiecutter --output-dir ./outputs --directory nautobot-app https://github.com/nautobot/cookiecutter-nautobot-app
+```
+
+## Templates
+
+There are the following templates available:
+
+- [`nautobot-app`](./nautobot-app) - A template for creating a new Nautobot app.
+- [`nautobot-app-ssot`](./nautobot-app-ssot) - A template for creating a new Nautobot app that is a Single Source of Truth (SSoT) app.

nautobot-app/hooks/post_gen_project.py

@@ -15,7 +15,7 @@
 * poetry shell
 * invoke makemigrations
 
-The file "creds.env will be ignored by git and can be used to override default environment variables.
+The file `creds.env` will be ignored by git and can be used to override default environment variables.
 """
 
 if __name__ == "__main__":

nautobot-app/{{ cookiecutter.project_slug }}/tasks.py

@@ -600,7 +600,7 @@ def bandit(context):
 
 @task
 def yamllint(context):
-    """Run yamllint to validate formating adheres to NTC defined YAML standards.
+    """Run yamllint to validate formatting adheres to NTC defined YAML standards.
 
     Args:
         context (obj): Used to run specific commands

tasks.py

@@ -436,7 +436,7 @@ def ruff(context, service=_DEFAULT_SERVICE, autoformat=False):
     }
 )
 def yamllint(context, service=_DEFAULT_SERVICE):
-    """Run yamllint to validate formating adheres to NTC defined YAML standards."""
+    """Run yamllint to validate formatting adheres to NTC defined YAML standards."""
     command = [
         *_prefix_command(context, service=service),
         "yamllint",
@@ -486,6 +486,40 @@ def help_task(context):
         context.run(f"invoke {task_name} --help", echo=True)
 
 
+@task(
+    help={
+        "debug": "Whether to run in debug mode (defaults to False)",
+        "input": "Whether to require user input, ignored with `--json-file` (defaults to True)",
+        "json-file": "Path to a JSON file containing answers to prompts (defaults to empty)",
+        "output-dir": "Path to the output directory (defaults to ./outputs)",
+        "template": "Path to the cookiecutter template to bake (defaults to ./nautobot-app)",
+    },
+)
+def bake(context, _debug=False, _input=True, json_file="", output_dir="./outputs", template="./nautobot-app"):
+    """Bake a new cookie from the template."""
+
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+    command = [
+        *_prefix_command(context),
+        "cookiecutter",
+        f"--output-dir={output_dir}",
+        f"--replay-file={json_file}" if json_file else "",
+    ]
+
+    if not _input:
+        command.append("--no-input")
+
+    if _debug:
+        command.append("--verbose")
+        command.append(f"--debug-file={output_dir}/debug.log")
+        command.append("--keep-project-on-failure")
+
+    command.append(template)
+
+    context.run(" ".join(command), pty=True)
+
+
 def _read_invoke_kwargs():
     result = {}