From ada12fe5bb5cff6ae30892ee555e0078b2e527d2 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Mon, 25 Sep 2023 11:45:57 +0000 Subject: [PATCH 1/5] chore: Align docs with SSoT --- docs/admin/{install/index.md => install.md} | 22 +++++----- .../aci_setup.md => integrations/aci.md} | 8 ++-- .../ansible.md} | 8 ++-- .../aristacv.md} | 8 ++-- .../grafana.md} | 8 ++-- .../ipfabric.md} | 8 ++-- .../meraki.md} | 8 ++-- .../panorama.md} | 8 ++-- .../mattermost.md} | 4 +- .../microsoft_teams.md} | 4 +- .../slack_setup.md => platforms/slack.md} | 4 +- .../webex_setup.md => platforms/webex.md} | 4 +- docs/dev/release_checklist.md | 2 +- docs/user/app_getting_started.md | 16 +++---- .../{aci_commands.md => integrations/aci.md} | 12 +++--- .../ansible.md} | 0 .../aristacv.md} | 6 +-- .../grafana.md} | 0 .../ipfabric.md} | 14 +++--- .../meraki.md} | 12 +++--- .../panorama.md} | 18 ++++---- mkdocs.yml | 43 ++++++++++--------- 22 files changed, 109 insertions(+), 108 deletions(-) rename docs/admin/{install/index.md => install.md} (92%) rename docs/admin/{install/aci_setup.md => integrations/aci.md} (91%) rename docs/admin/{install/ansible_setup.md => integrations/ansible.md} (91%) rename docs/admin/{install/aristacv_setup.md => integrations/aristacv.md} (93%) rename docs/admin/{install/grafana_setup.md => integrations/grafana.md} (93%) rename docs/admin/{install/ipfabric_setup.md => integrations/ipfabric.md} (92%) rename docs/admin/{install/meraki_setup.md => integrations/meraki.md} (87%) rename docs/admin/{install/panorama_setup.md => integrations/panorama.md} (89%) rename docs/admin/{install/mattermost_setup.md => platforms/mattermost.md} (92%) rename docs/admin/{install/microsoft_teams_setup.md => platforms/microsoft_teams.md} (96%) rename docs/admin/{install/slack_setup.md => platforms/slack.md} (99%) rename docs/admin/{install/webex_setup.md => platforms/webex.md} (95%) rename docs/user/{aci_commands.md => integrations/aci.md} (82%) rename docs/user/{ansible_commands.md => integrations/ansible.md} (100%) rename docs/user/{aristacv_commands.md => integrations/aristacv.md} (88%) rename docs/user/{grafana_commands.md => integrations/grafana.md} (100%) rename docs/user/{ipfabric_commands.md => integrations/ipfabric.md} (87%) rename docs/user/{meraki_commands.md => integrations/meraki.md} (89%) rename docs/user/{panorama_commands.md => integrations/panorama.md} (73%) diff --git a/docs/admin/install/index.md b/docs/admin/install.md similarity index 92% rename from docs/admin/install/index.md rename to docs/admin/install.md index e01fd168..65595982 100644 --- a/docs/admin/install/index.md +++ b/docs/admin/install.md @@ -58,10 +58,10 @@ The `nautobot-chatops` package supports multiple chat platforms. Set up your chosen chat platform: -- [Mattermost](./mattermost_setup.md) -- [Microsoft Teams](./microsoft_teams_setup.md) -- [Slack](./slack_setup.md) -- [Cisco Webex](./webex_setup.md) +- [Mattermost](./platforms/mattermost.md) +- [Microsoft Teams](./platforms/microsoft_teams.md) +- [Slack](./platforms/slack.md) +- [Cisco Webex](./platforms/webex.md) ## Installation Guide @@ -145,10 +145,10 @@ The `nautobot-chatops` package includes multiple integrations. Each requires ext Set up integrations using the specific guides: -- [Cisco ACI](./aci_setup.md) -- [AWX / Ansible Tower](./ansible_setup.md) -- [Arista CloudVision](./aristacv_setup.md) -- [Grafana](./grafana_setup.md) -- [IPFabric](./ipfabric_setup.md) -- [Cisco Meraki](./meraki_setup.md) -- [Palo Alto Panorama](./panorama_setup.md) +- [Cisco ACI](./integrations/aci.md) +- [AWX / Ansible Tower](./integrations/ansible.md) +- [Arista CloudVision](./integrations/aristacv.md) +- [Grafana](./integrations/grafana.md) +- [IPFabric](./integrations/ipfabric.md) +- [Cisco Meraki](./integrations/meraki.md) +- [Palo Alto Panorama](./integrations/panorama.md) diff --git a/docs/admin/install/aci_setup.md b/docs/admin/integrations/aci.md similarity index 91% rename from docs/admin/install/aci_setup.md rename to docs/admin/integrations/aci.md index ba776522..a8b2468e 100644 --- a/docs/admin/install/aci_setup.md +++ b/docs/admin/integrations/aci.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Cisco ACI integration with the Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[aci] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `aci` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `aci` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -66,7 +66,7 @@ When executing chat commands, you will be presented with a selection dialog cont ## Upgrading from `nautobot-plugin-chatops-aci` App !!! warning - When upgrading from `nautobot-plugin-chatops-aci` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-aci` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/ansible_setup.md b/docs/admin/integrations/ansible.md similarity index 91% rename from docs/admin/install/ansible_setup.md rename to docs/admin/integrations/ansible.md index 63e5af9f..a04f8a9a 100644 --- a/docs/admin/install/ansible_setup.md +++ b/docs/admin/integrations/ansible.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up AWX / Ansible Tower integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[ansible] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `ansible` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `ansible` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -52,7 +52,7 @@ PLUGINS_CONFIG = { ## Upgrading from `nautobot-plugin-chatops-ansible` App !!! warning - When upgrading from `nautobot-plugin-chatops-ansible` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-ansible` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/aristacv_setup.md b/docs/admin/integrations/aristacv.md similarity index 93% rename from docs/admin/install/aristacv_setup.md rename to docs/admin/integrations/aristacv.md index 48309d1a..90bbaba8 100644 --- a/docs/admin/install/aristacv_setup.md +++ b/docs/admin/integrations/aristacv.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Arista CloudVision integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[aristacv] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `aristacv` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `aristacv` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -69,7 +69,7 @@ Once you have updated your environment file, restart both nautobot and nautobot- ## Upgrading from `nautobot-plugin-chatops-arista-cloudvision` App !!! warning - When upgrading from `nautobot-plugin-chatops-arista-cloudvision` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-arista-cloudvision` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/grafana_setup.md b/docs/admin/integrations/grafana.md similarity index 93% rename from docs/admin/install/grafana_setup.md rename to docs/admin/integrations/grafana.md index 84b4e407..d09522ec 100644 --- a/docs/admin/install/grafana_setup.md +++ b/docs/admin/integrations/grafana.md @@ -6,18 +6,18 @@ This guide will walk you through steps to set up Grafana integration with the `n Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[grafana] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). - [Grafana](https://grafana.com/docs/grafana/latest/installation/) application installed and configured with dashboards and panels. - [Grafana Image Rendering Service](https://grafana.com/docs/grafana/latest/administration/image_rendering/) installed. - [Grafana Image Rending Plugin for Grafana](https://grafana.com/grafana/plugins/grafana-image-renderer/) installed in your Grafana application. ## Command Setup -Create a top-level command named `grafana` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `grafana` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -62,7 +62,7 @@ PLUGINS_CONFIG = { ## Upgrading from `nautobot-plugin-chatops-grafana` App !!! warning - When upgrading from `nautobot-plugin-chatops-grafana` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-grafana` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/ipfabric_setup.md b/docs/admin/integrations/ipfabric.md similarity index 92% rename from docs/admin/install/ipfabric_setup.md rename to docs/admin/integrations/ipfabric.md index aeff7d2c..c1f38326 100644 --- a/docs/admin/install/ipfabric_setup.md +++ b/docs/admin/integrations/ipfabric.md @@ -6,11 +6,11 @@ This guide will walk you through steps to set up IPFabric integration with the ` Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[ipfabric] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Version Matrix @@ -25,7 +25,7 @@ Here is a compatibility matrix and the minimum versions required to run this plu ## Command Setup -Create a top-level command named `ipfabric` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `ipfabric` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -59,7 +59,7 @@ PLUGINS_CONFIG = { ## Upgrading from `nautobot-plugin-chatops-ipfabric` App !!! warning - When upgrading from `nautobot-plugin-chatops-ipfabric` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-ipfabric` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/meraki_setup.md b/docs/admin/integrations/meraki.md similarity index 87% rename from docs/admin/install/meraki_setup.md rename to docs/admin/integrations/meraki.md index 6506931f..e3173812 100644 --- a/docs/admin/install/meraki_setup.md +++ b/docs/admin/integrations/meraki.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Cisco Meraki integration with t Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[meraki] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `meraki` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `meraki` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -46,7 +46,7 @@ The alternative option is to set the environmental variable: ## Upgrading from `nautobot-plugin-chatops-meraki` App !!! warning - When upgrading from `nautobot-plugin-chatops-meraki` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-meraki` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/panorama_setup.md b/docs/admin/integrations/panorama.md similarity index 89% rename from docs/admin/install/panorama_setup.md rename to docs/admin/integrations/panorama.md index 1907ca97..63e29011 100644 --- a/docs/admin/install/panorama_setup.md +++ b/docs/admin/integrations/panorama.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Palo Alto Panorama integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./index.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). ```shell pip install nautobot-chatops[panorama] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./index.md#chat-platforms-configuration) and [tested](./index.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `panorama` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./index.md#chat-platforms-configuration). +Create a top-level command named `panorama` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). ## Configuration @@ -46,7 +46,7 @@ PLUGINS_CONFIG = { ## Upgrading from `nautobot-plugin-chatops-panorama` App !!! warning - When upgrading from `nautobot-plugin-chatops-panorama` App, it's necessary to [avoid conflicts](index.md#potential-apps-conflicts). + When upgrading from `nautobot-plugin-chatops-panorama` App, it's necessary to [avoid conflicts](../install.md#potential-apps-conflicts). - Uninstall the old App: ```shell diff --git a/docs/admin/install/mattermost_setup.md b/docs/admin/platforms/mattermost.md similarity index 92% rename from docs/admin/install/mattermost_setup.md rename to docs/admin/platforms/mattermost.md index 40ac69b4..92e8ba6d 100644 --- a/docs/admin/install/mattermost_setup.md +++ b/docs/admin/platforms/mattermost.md @@ -25,7 +25,7 @@ - Copy the displayed url matching the Server you want to add the chatbot to. - Make sure to include the `http://` or `https://`. - If shown, make sure to include the port. Ex. `https://example.com:8065` -6. Proceed to the [Install Guide](index.md#Install-Guide) section. +6. Proceed to the [Install Guide](../install.md#Install-Guide) section. **Note:** For every Slash Command created for Mattermost, a separate token will be generated. @@ -39,4 +39,4 @@ ## General Chat Setup Instructions -See [admin_install](index.md) instructions here for general plugin setup instructions. +See [admin_install](../install.md) instructions here for general plugin setup instructions. diff --git a/docs/admin/install/microsoft_teams_setup.md b/docs/admin/platforms/microsoft_teams.md similarity index 96% rename from docs/admin/install/microsoft_teams_setup.md rename to docs/admin/platforms/microsoft_teams.md index ac3b2ac5..ff0ea783 100644 --- a/docs/admin/install/microsoft_teams_setup.md +++ b/docs/admin/platforms/microsoft_teams.md @@ -36,7 +36,7 @@ 1. In the Microsoft Teams client, select “Apps” from the sidebar to the left. 2. Select “Built for your org.” 3. Select the tile for the new Nautobot app. Click the blue “Add” button. -4. Proceed to the [Install Guide](index.md#Install-Guide) section. +4. Proceed to the [Install Guide](../install.md#Install-Guide) section. ## Nautobot Config @@ -53,4 +53,4 @@ Reference the [Setting Up Nautobot ChatOps With MSTeams Fall 2022](https://blog. ## General Chat Setup Instructions -See [admin_install](index.md) instructions here for general plugin setup instructions. +See [admin_install](../install.md) instructions here for general plugin setup instructions. diff --git a/docs/admin/install/slack_setup.md b/docs/admin/platforms/slack.md similarity index 99% rename from docs/admin/install/slack_setup.md rename to docs/admin/platforms/slack.md index d12c5f86..1f59b7bd 100644 --- a/docs/admin/install/slack_setup.md +++ b/docs/admin/platforms/slack.md @@ -138,7 +138,7 @@ PLUGINS_CONFIG = { ![slack integration invite](../../images/add_nautobot.png) -Once these steps are completed, you can proceed to the [Install Guide](index.md#Install-Guide) section. +Once these steps are completed, you can proceed to the [Install Guide](../install.md#Install-Guide) section. ## Configuring Multiple Chatbots in a Workspace @@ -186,7 +186,7 @@ PLUGINS_CONFIG = { ## General Chat Setup Instructions -See [admin_install](index.md) instructions here for general plugin setup instructions. +See [admin_install](../install.md) instructions here for general plugin setup instructions. ## Startup Slack Sockets (Socket Mode) diff --git a/docs/admin/install/webex_setup.md b/docs/admin/platforms/webex.md similarity index 95% rename from docs/admin/install/webex_setup.md rename to docs/admin/platforms/webex.md index b282f64d..a65d9fa9 100644 --- a/docs/admin/install/webex_setup.md +++ b/docs/admin/platforms/webex.md @@ -28,7 +28,7 @@ - secret: (enter a secret string that you don't mind having passed around as plaintext) - Change the `resource` to "attachmentActions" and run the API call again to create a second webhook. 4. Configure the `webex_signing_secret` in your `.creds.env` to match the Webhook secret string that you selected above. -5. Proceed to the [Installation Guide](index.md#Install-Guide) section. +5. Proceed to the [Installation Guide](../install.md#Install-Guide) section. ## Deprecation Warning @@ -60,4 +60,4 @@ Both settings will currently work, however support for `enable_webex_teams`, `we ## General Chat Setup Instructions -See [admin_install](index.md) instructions here for general plugin setup instructions. +See [admin_install](../install.md) instructions here for general plugin setup instructions. diff --git a/docs/dev/release_checklist.md b/docs/dev/release_checklist.md index d31d8c4f..1455133b 100644 --- a/docs/dev/release_checklist.md +++ b/docs/dev/release_checklist.md @@ -49,7 +49,7 @@ Add the release notes (`docs/release-notes/X.Y.md`) to the table of contents wit ### Verify and Revise the Installation Documentation -Follow the [installation instructions](../admin/install/index.md) to perform a new production installation of Nautobot ChatOps. +Follow the [installation instructions](../admin/install.md) to perform a new production installation of Nautobot ChatOps. The goal of this step is to walk through the entire install process *as documented* to make sure nothing there needs to be changed or updated, to catch any errors or omissions in the documentation, and to ensure that it is current with each release. diff --git a/docs/user/app_getting_started.md b/docs/user/app_getting_started.md index c2da634b..4a30aeab 100644 --- a/docs/user/app_getting_started.md +++ b/docs/user/app_getting_started.md @@ -4,7 +4,7 @@ A step-by-step tutorial on how to get the App going and how to use it. ## Install the App -To install the App, please follow the instructions detailed in the [Administrator Guide](../admin/install/index.md). +To install the App, please follow the instructions detailed in the [Administrator Guide](../admin/install.md). ## Link Nautobot Account @@ -52,10 +52,10 @@ Interact with Nautobot by utilizing the following sub-commands: The `nautobot-chatops` package includes multiple integrations. Each integration adds chat commands described here: -- [Cisco ACI](./aci_commands.md) -- [AWX / Ansible Tower](./ansible_commands.md) -- [Arista CloudVision](./aristacv_commands.md) -- [Grafana](./grafana_commands.md) -- [IPFabric](./ipfabric_commands.md) -- [Cisco Meraki](./meraki_commands.md) -- [Palo Alto Panorama](./panorama_commands.md) +- [Cisco ACI](./integrations/aci.md) +- [AWX / Ansible Tower](./integrations/ansible.md) +- [Arista CloudVision](./integrations/aristacv.md) +- [Grafana](./integrations/grafana.md) +- [IPFabric](./integrations/ipfabric.md) +- [Cisco Meraki](./integrations/meraki.md) +- [Palo Alto Panorama](./integrations/panorama.md) diff --git a/docs/user/aci_commands.md b/docs/user/integrations/aci.md similarity index 82% rename from docs/user/aci_commands.md rename to docs/user/integrations/aci.md index 40e71756..9b6416fa 100644 --- a/docs/user/aci_commands.md +++ b/docs/user/integrations/aci.md @@ -25,16 +25,16 @@ Interact with Cisco ACI by utilizing the following sub-commands: ### Slack -![image](../images/aci-slack-get-tenants.png) +![image](../../images/aci-slack-get-tenants.png) -![image](../images/aci-slack-get-epg-details.png) +![image](../../images/aci-slack-get-epg-details.png) -![image](../images/aci-slack-get-bds.png) +![image](../../images/aci-slack-get-bds.png) ### Cisco Webex -![image](../images/aci-slack-get-tenants.png) +![image](../../images/aci-slack-get-tenants.png) -![image](../images/aci-slack-get-epg-details.png) +![image](../../images/aci-slack-get-epg-details.png) -![image](../images/aci-slack-get-bds.png) +![image](../../images/aci-slack-get-bds.png) diff --git a/docs/user/ansible_commands.md b/docs/user/integrations/ansible.md similarity index 100% rename from docs/user/ansible_commands.md rename to docs/user/integrations/ansible.md diff --git a/docs/user/aristacv_commands.md b/docs/user/integrations/aristacv.md similarity index 88% rename from docs/user/aristacv_commands.md rename to docs/user/integrations/aristacv.md index 8ee52bd9..465cc265 100644 --- a/docs/user/aristacv_commands.md +++ b/docs/user/integrations/aristacv.md @@ -20,8 +20,8 @@ Interact with Arista CloudVision by utilizing the following sub-commands: ## Screenshots -![image](../images/aristacv-get-device-cve.png) +![image](../../images/aristacv-get-device-cve.png) -![image](../images/aristacv-get-configlet.png) +![image](../../images/aristacv-get-configlet.png) -![image](../images/aristacv-get-device-cve.png) +![image](../../images/aristacv-get-device-cve.png) diff --git a/docs/user/grafana_commands.md b/docs/user/integrations/grafana.md similarity index 100% rename from docs/user/grafana_commands.md rename to docs/user/integrations/grafana.md diff --git a/docs/user/ipfabric_commands.md b/docs/user/integrations/ipfabric.md similarity index 87% rename from docs/user/ipfabric_commands.md rename to docs/user/integrations/ipfabric.md index 053c0941..13213c3c 100644 --- a/docs/user/ipfabric_commands.md +++ b/docs/user/integrations/ipfabric.md @@ -25,16 +25,16 @@ IP Fabric uses a concept of snapshots which can include different devices and da ## Screenshots -![image](../images/ipfabric-1.png) +![image](../../images/ipfabric-1.png) -![image](../images/ipfabric-2.png) +![image](../../images/ipfabric-2.png) -![image](../images/ipfabric-3.png) +![image](../../images/ipfabric-3.png) -![image](../images/ipfabric-4.png) +![image](../../images/ipfabric-4.png) -![image](../images/ipfabric-5.png) +![image](../../images/ipfabric-5.png) -![image](../images/ipfabric-6.png) +![image](../../images/ipfabric-6.png) -![image](../images/ipfabric-7.png) +![image](../../images/ipfabric-7.png) diff --git a/docs/user/meraki_commands.md b/docs/user/integrations/meraki.md similarity index 89% rename from docs/user/meraki_commands.md rename to docs/user/integrations/meraki.md index 701f4d88..d114666d 100644 --- a/docs/user/meraki_commands.md +++ b/docs/user/integrations/meraki.md @@ -27,15 +27,15 @@ Interact with Cisco Meraki by utilizing the following sub-commands: Running `/meraki get-organizations`. -![Example output for get-organizations](../images/00-meraki-get-orgs.png) +![Example output for get-organizations](../../images/00-meraki-get-orgs.png) Running `/meraki get-networks`. -![Example output for get-networks](../images/00-meraki-get-networks.png) +![Example output for get-networks](../../images/00-meraki-get-networks.png) Running `/meraki get-switchports-status`. -![Example output for get-networks](../images/00-meraki-get-port-stats.png) +![Example output for get-networks](../../images/00-meraki-get-port-stats.png) Since the output was cut off the output example is below: @@ -62,12 +62,12 @@ To demonstrate a example of configuration updates. There is a simple configurat Specify Org, Switch, and Port ID. -![Example output for config-port0](../images/00-meraki-port-config.png) +![Example output for config-port0](../../images/00-meraki-port-config.png) Fill out the Port Specific Configuration. -![Example output for config-port1](../images/01-meraki-port-config.png) +![Example output for config-port1](../../images/01-meraki-port-config.png) Result of the configuration. -![Example output for config-port2](../images/02-meraki-port-config.png) +![Example output for config-port2](../../images/02-meraki-port-config.png) diff --git a/docs/user/panorama_commands.md b/docs/user/integrations/panorama.md similarity index 73% rename from docs/user/panorama_commands.md rename to docs/user/integrations/panorama.md index 9eb6e752..a4332e30 100644 --- a/docs/user/panorama_commands.md +++ b/docs/user/integrations/panorama.md @@ -21,20 +21,20 @@ Interact with Palo Alto Panorama by utilizing the following sub-commands: ## Screenshots -![Help](../images/panorama-01.png) +![Help](../../images/panorama-01.png) -![Validate Rule Exists Success](../images/panorama-02.png) +![Validate Rule Exists Success](../../images/panorama-02.png) -![Validate Rule Exists Failure](../images/panorama-03.png) +![Validate Rule Exists Failure](../../images/panorama-03.png) -![Upload Software](../images/panorama-04.png) +![Upload Software](../../images/panorama-04.png) -![Capture Traffic Filter](../images/panorama-05.png) +![Capture Traffic Filter](../../images/panorama-05.png) -![Capture Traffic](../images/panorama-06.png) +![Capture Traffic](../../images/panorama-06.png) -![Get Devices](../images/panorama-07.png) +![Get Devices](../../images/panorama-07.png) -![Get DeviceGroups](../images/panorama-08.png) +![Get Device Groups](../../images/panorama-08.png) -![Get Device Rules](../images/panorama-09.png) +![Get Device Rules](../../images/panorama-09.png) diff --git a/mkdocs.yml b/mkdocs.yml index 8ead7041..8a35c26f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,29 +101,30 @@ nav: - User Guide: - App Overview: "user/app_overview.md" - Getting Started: "user/app_getting_started.md" - - Frequently Asked Questions: "user/app_faq.md" - Integrations: - - "user/aci_commands.md" - - "user/ansible_commands.md" - - "user/aristacv_commands.md" - - "user/grafana_commands.md" - - "user/ipfabric_commands.md" - - "user/meraki_commands.md" - - "user/panorama_commands.md" + - "user/integrations/aci.md" + - "user/integrations/ansible.md" + - "user/integrations/aristacv.md" + - "user/integrations/grafana.md" + - "user/integrations/ipfabric.md" + - "user/integrations/meraki.md" + - "user/integrations/panorama.md" + - Frequently Asked Questions: "user/app_faq.md" - Administrator Guide: - - Install and Configure: - - "admin/install/index.md" - - "admin/install/slack_setup.md" - - "admin/install/mattermost_setup.md" - - "admin/install/webex_setup.md" - - "admin/install/microsoft_teams_setup.md" - - "admin/install/aci_setup.md" - - "admin/install/ansible_setup.md" - - "admin/install/aristacv_setup.md" - - "admin/install/grafana_setup.md" - - "admin/install/ipfabric_setup.md" - - "admin/install/meraki_setup.md" - - "admin/install/panorama_setup.md" + - Install and Configure: "admin/install.md" + - Platforms: + - "admin/platforms/slack.md" + - "admin/platforms/mattermost.md" + - "admin/platforms/webex.md" + - "admin/platforms/microsoft_teams.md" + - Integrations: + - "admin/integrations/aci.md" + - "admin/integrations/ansible.md" + - "admin/integrations/aristacv.md" + - "admin/integrations/grafana.md" + - "admin/integrations/ipfabric.md" + - "admin/integrations/meraki.md" + - "admin/integrations/panorama.md" - Upgrade: "admin/upgrade.md" - Uninstall: "admin/uninstall.md" - Compatibility Matrix: "admin/compatibility_matrix.md" From 187fcf734ec54e069cd9a6cbae8bb85a4bcc016e Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Mon, 25 Sep 2023 11:49:40 +0000 Subject: [PATCH 2/5] fix: Add changelog fragment --- changes/265.changed | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/265.changed diff --git a/changes/265.changed b/changes/265.changed new file mode 100644 index 00000000..5dbed3a4 --- /dev/null +++ b/changes/265.changed @@ -0,0 +1 @@ +Aligned integrations documentation structure with SSoT. From 463cd2dcf25e269c0a3da2c63ee2e7b2b2f88db4 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Thu, 1 Feb 2024 08:27:01 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Cristian --- docs/admin/integrations/aci.md | 6 +++--- docs/admin/integrations/ansible.md | 6 +++--- docs/admin/integrations/aristacv.md | 6 +++--- docs/admin/integrations/grafana.md | 6 +++--- docs/admin/integrations/ipfabric.md | 6 +++--- docs/admin/integrations/meraki.md | 6 +++--- docs/admin/integrations/panorama.md | 6 +++--- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/admin/integrations/aci.md b/docs/admin/integrations/aci.md index dc4f226d..9109b8d4 100644 --- a/docs/admin/integrations/aci.md +++ b/docs/admin/integrations/aci.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Cisco ACI integration with the Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[aci] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `aci` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `aci` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/ansible.md b/docs/admin/integrations/ansible.md index ea81b323..8be859e5 100644 --- a/docs/admin/integrations/ansible.md +++ b/docs/admin/integrations/ansible.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up AWX / Ansible Tower integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[ansible] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `ansible` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `ansible` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/aristacv.md b/docs/admin/integrations/aristacv.md index 211b14d3..00ecd78e 100644 --- a/docs/admin/integrations/aristacv.md +++ b/docs/admin/integrations/aristacv.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Arista CloudVision integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[aristacv] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `aristacv` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `aristacv` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/grafana.md b/docs/admin/integrations/grafana.md index a5568732..13f6f563 100644 --- a/docs/admin/integrations/grafana.md +++ b/docs/admin/integrations/grafana.md @@ -6,18 +6,18 @@ This guide will walk you through steps to set up Grafana integration with the `n Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[grafana] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). - [Grafana](https://grafana.com/docs/grafana/latest/installation/) application installed and configured with dashboards and panels. - [Grafana Image Rendering Service](https://grafana.com/docs/grafana/latest/administration/image_rendering/) installed. - [Grafana Image Rending App for Grafana](https://grafana.com/grafana/plugins/grafana-image-renderer/) installed in your Grafana application. ## Command Setup -Create a top-level command named `grafana` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `grafana` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/ipfabric.md b/docs/admin/integrations/ipfabric.md index d2645e7b..f1b27bf3 100644 --- a/docs/admin/integrations/ipfabric.md +++ b/docs/admin/integrations/ipfabric.md @@ -6,11 +6,11 @@ This guide will walk you through steps to set up IPFabric integration with the ` Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[ipfabric] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Version Matrix @@ -25,7 +25,7 @@ Here is a compatibility matrix and the minimum versions required to run this app ## Command Setup -Create a top-level command named `ipfabric` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `ipfabric` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/meraki.md b/docs/admin/integrations/meraki.md index f1115418..5988a1b2 100644 --- a/docs/admin/integrations/meraki.md +++ b/docs/admin/integrations/meraki.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Cisco Meraki integration with t Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[meraki] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `meraki` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `meraki` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration diff --git a/docs/admin/integrations/panorama.md b/docs/admin/integrations/panorama.md index fd432c31..70be3ff4 100644 --- a/docs/admin/integrations/panorama.md +++ b/docs/admin/integrations/panorama.md @@ -6,15 +6,15 @@ This guide will walk you through steps to set up Palo Alto Panorama integration Before configuring the integration, please ensure the following: -- `nautobot-chatops` App was [installed with integration extra dependencies](./../install.md#installation-guide). +- `nautobot-chatops` App was [installed with integration extra dependencies](../install.md#installation-guide). ```shell pip install nautobot-chatops[panorama] ``` -- `nautobot-chatops` App is set up with at least one [enabled chat platform](./../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). +- `nautobot-chatops` App is set up with at least one [enabled chat platform](../install.md#chat-platforms-configuration) and [tested](./../install.md#test-your-chatbot). ## Command Setup -Create a top-level command named `panorama` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](./../install.md#chat-platforms-configuration). +Create a top-level command named `panorama` in your enabled chat platform. For detailed instructions related to your specific chat platform, refer to the [platform specific set up](../install.md#chat-platforms-configuration). ## Configuration From 78ccc874d445cec992d4aaaa43b83b9e5d4b5421 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Thu, 1 Feb 2024 07:40:42 +0000 Subject: [PATCH 4/5] fix: admin install doc links --- docs/admin/install.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/install.md b/docs/admin/install.md index 75164591..f0942106 100644 --- a/docs/admin/install.md +++ b/docs/admin/install.md @@ -13,7 +13,7 @@ This guide outlines the process of enabling Nautobot ChatOps, which includes: - [Test Your Chatbot](#test-your-chatbot) - [Integrations Configuration](#integrations-configuration) -{% include-markdown '../../glossary.md' heading-offset=1 %} +{% include-markdown '../glossary.md' heading-offset=1 %} ## Prerequisites @@ -126,7 +126,7 @@ Adjust the App's behavior with the following settings: ## Granting Access to the Chat Platform {% - include-markdown '../../models/accessgrant.md' + include-markdown '../models/accessgrant.md' start='' heading-offset=1 %} @@ -134,7 +134,7 @@ Adjust the App's behavior with the following settings: ## Link Nautobot Account {% - include-markdown '../../models/chatopsaccountlink.md' + include-markdown '../models/chatopsaccountlink.md' start='' heading-offset=1 %} From 31615b18c8e6f4e8eac8dbad3e74c4112f5302fc Mon Sep 17 00:00:00 2001 From: Stephen Kiely Date: Mon, 5 Feb 2024 11:30:15 -0600 Subject: [PATCH 5/5] Fix Version Annotations --- docs/admin/install.md | 5 ++--- docs/models/chatopsaccountlink.md | 2 +- docs/user/app_getting_started.md | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/admin/install.md b/docs/admin/install.md index f0942106..a432d036 100644 --- a/docs/admin/install.md +++ b/docs/admin/install.md @@ -107,9 +107,8 @@ PLUGINS_CONFIG = { } ``` -+++3.0.0 - -Some configuration settings have now been added to the Nautobot Admin Config page. See [Nautobot Admin](https://docs.nautobot.com/projects/core/en/stable/configuration/optional-settings/?h=administr#administratively-configurable-settings) ++++ 3.0.0 + Some configuration settings have now been added to the Nautobot Admin Config page. See [Nautobot Admin](https://docs.nautobot.com/projects/core/en/stable/configuration/optional-settings/?h=administr#administratively-configurable-settings) ## Configuration Guide diff --git a/docs/models/chatopsaccountlink.md b/docs/models/chatopsaccountlink.md index 56746302..a1eb488c 100644 --- a/docs/models/chatopsaccountlink.md +++ b/docs/models/chatopsaccountlink.md @@ -1,7 +1,7 @@ # Account Link -+++3.0.0 ++++ 3.0.0 Nautobot ChatOps now uses the built-in Nautobot permissions for Nautobot Objects (Devices, Locations, Racks, etc.). Each user will need to link their Nautobot Account with their Chat Platform User Account. Login to Nautobot then access the Link ChatOps Account within the Plugins menu. Here you can provide your email address and select the ChatOps Platform you are using, then click the Look up User ID from Email to get your Chat User ID. diff --git a/docs/user/app_getting_started.md b/docs/user/app_getting_started.md index b304f49a..89bb62ed 100644 --- a/docs/user/app_getting_started.md +++ b/docs/user/app_getting_started.md @@ -8,7 +8,7 @@ To install the App, please follow the instructions detailed in the [Administrato ## Link Nautobot Account -+++3.0.0 ++++ 3.0.0 Nautobot ChatOps now uses the built-in Nautobot permissions for Nautobot Objects (Devices, Locations, Racks, etc.). Each user will need to link their Nautobot Account with their Chat Platform User Account. Login to Nautobot then access the Link ChatOps Account within the Plugins menu. Here you can provide your email address and select the ChatOps Platform you are using, then click the Look up User ID from Email to get your Chat User ID.