merge commit

.readthedocs.yaml

@@ -0,0 +1,22 @@
+---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python in the build environment.
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+mkdocs:
+  configuration: "mkdocs.yml"
+  fail_on_warning: true
+
+# Use our docs/requirements.txt during installation.
+python:
+  install:
+    - requirements: "docs/requirements.txt"

README.md

@@ -17,173 +17,6 @@ The following templates are 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 extends the capabilities of the Nautobot Single Source of Truth (SSoT) App. The [Nautobot SSoT App](https://github.com/nautobot/nautobot-plugin-ssot) facilitates integration and data synchronization between various "source of truth" (SoT) systems, with Nautobot acting as a central clearinghouse for data.
 
-## Local Quick-start
-
-For local usage or development.
-
-Pre-requisites:
-
-- Docker and Docker Compose
-- git
-- Python 3.8+
-- Invoke
-
-Clone the repository:
-
-```shell
-git clone [email protected]:nautobot/cookiecutter-nautobot-app.git
-cd cookiecutter-nautobot-app
-```
-
-Run all tests:
-
-```shell
-invoke tests
-```
-
-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-quick-start).
-
-Then, you can use the following command:
-
-```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
 
@@ -195,7 +28,7 @@ Pre-requisites:
 
 ```shell
 pip install cookiecutter
-mkdir outpus
+mkdir outputs
 ```
 
 Then run the following command:

docs/assets/extra.css

@@ -0,0 +1,161 @@
+:root>* {
+    --md-accent-fg-color: #ff8504;
+    --md-primary-fg-color: #ff8504;
+    --md-typeset-a-color: #0097ff;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-default-bg-color: hsla(var(--md-hue), 0%, 15%, 1);
+    --md-typeset-a-color: #0097ff;
+}
+
+/* Accessibility: Increase fonts for dark theme */
+[data-md-color-scheme="slate"] .md-typeset {
+    font-size: 0.9rem;
+}
+
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) {
+    font-size: 0.7rem;
+}
+
+/*
+* The default max-width is 61rem which does not provide nearly enough space to present code examples or larger tables
+*/
+.md-grid {
+    margin-left: auto;
+    margin-right: auto;
+    max-width: 95%;
+}
+
+.md-tabs__link {
+    font-size: 0.8rem;
+}
+
+.md-tabs__link--active {
+    color: var(--md-primary-fg-color);
+}
+
+.md-header__button.md-logo :is(img, svg) {
+    height: 2rem;
+}
+
+.md-header__button.md-logo :-webkit-any(img, svg) {
+    height: 2rem;
+}
+
+.md-header__title {
+    font-size: 1.2rem;
+}
+
+img.logo {
+    height: 200px;
+}
+
+img.copyright-logo {
+    height: 24px;
+    vertical-align: middle;
+}
+
+[data-md-color-primary=black] .md-header {
+    background-color: #212121;
+}
+
+@media screen and (min-width: 76.25em) {
+    [data-md-color-primary=black] .md-tabs {
+        background-color: #212121;
+    }
+}
+
+/* Customization for mkdocstrings */
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: .2rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.autorefs-external::after {
+    /* https://primer.style/octicons/arrow-up-right-24 */
+    background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    content: ' ';
+
+    display: inline-block;
+    position: relative;
+    top: 0.1em;
+    margin-left: 0.2em;
+    margin-right: 0.1em;
+
+    height: 1em;
+    width: 1em;
+    border-radius: 100%;
+    background-color: var(--md-typeset-a-color);
+}
+
+a.autorefs-external:hover::after {
+    background-color: var(--md-accent-fg-color);
+}
+
+
+/* Customization for mkdocs-version-annotations */
+:root {
+    /* Icon for "version-added" admonition: Material Design Icons "plus-box-outline" */
+    --md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 19V5H5v14h14m0-16a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h14m-8 4h2v4h4v2h-4v4h-2v-4H7v-2h4V7Z"/></svg>');
+    /* Icon for "version-changed" admonition: Material Design Icons "delta" */
+    --md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7.77 18.39 18H5.61L12 7.77M12 4 2 20h20"/></svg>');
+    /* Icon for "version-removed" admonition: Material Design Icons "minus-circle-outline" */
+    --md-admonition-icon--version-removed: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2M7 13h10v-2H7"/></svg>');
+}
+
+/* "version-added" admonition in green */
+.md-typeset .admonition.version-added,
+.md-typeset details.version-added {
+    border-color: rgb(0, 200, 83);
+}
+
+.md-typeset .version-added>.admonition-title,
+.md-typeset .version-added>summary {
+    background-color: rgba(0, 200, 83, .1);
+}
+
+.md-typeset .version-added>.admonition-title::before,
+.md-typeset .version-added>summary::before {
+    background-color: rgb(0, 200, 83);
+    -webkit-mask-image: var(--md-admonition-icon--version-added);
+    mask-image: var(--md-admonition-icon--version-added);
+}
+
+/* "version-changed" admonition in orange */
+.md-typeset .admonition.version-changed,
+.md-typeset details.version-changed {
+    border-color: rgb(255, 145, 0);
+}
+
+.md-typeset .version-changed>.admonition-title,
+.md-typeset .version-changed>summary {
+    background-color: rgba(255, 145, 0, .1);
+}
+
+.md-typeset .version-changed>.admonition-title::before,
+.md-typeset .version-changed>summary::before {
+    background-color: rgb(255, 145, 0);
+    -webkit-mask-image: var(--md-admonition-icon--version-changed);
+    mask-image: var(--md-admonition-icon--version-changed);
+}
+
+/* "version-removed" admonition in red */
+.md-typeset .admonition.version-removed,
+.md-typeset details.version-removed {
+    border-color: rgb(255, 82, 82);
+}
+
+.md-typeset .version-removed>.admonition-title,
+.md-typeset .version-removed>summary {
+    background-color: rgba(255, 82, 82, .1);
+}
+
+.md-typeset .version-removed>.admonition-title::before,
+.md-typeset .version-removed>summary::before {
+    background-color: rgb(255, 82, 82);
+    -webkit-mask-image: var(--md-admonition-icon--version-removed);
+    mask-image: var(--md-admonition-icon--version-removed);
+}