Merge pull request #149 from smk4664/docs-update

Docs update

.github/workflows/ci.yml

@@ -101,11 +101,11 @@ jobs:
       fail-fast: true
       matrix:
         python-version: ["3.7", "3.8", "3.9"]
-        nautobot-version: ["1.1.6", "1.2.11", "1.3.0"]
+        nautobot-version: ["1.3.0", "1.4.2"]
         # Also test Python 3.10 with Nautobot 1.3.x
         include:
           - python-version: "3.10"
-            nautobot-version: "1.3.0"
+            nautobot-version: "1.4.2"
     runs-on: "ubuntu-20.04"
     env:
       INVOKE_NAUTOBOT_CHATOPS_PYTHON_VER: "${{ matrix.python-version }}"
@@ -121,22 +121,9 @@ jobs:
         run: "cp development/creds.example.env development/creds.env"
       - name: "Remove Poetry Lock for Older Nautobot Tests"
         run: "rm -f poetry.lock"
-        if: "matrix.nautobot-version != '1.3.0'"
-      - name: "Remove Black"
-        # We have dependency issues specifically with Nautobot 1.1 but we really don't care about black
-        # on Anything less than the latest
-        if: "matrix.nautobot-version != '1.3.0'"
-        run: "poetry remove black --dev"
-      - name: "Handle Markupsafe bug"
-        # Markupsafe 2.0.1 conflicts with the new jinja, but 2.1.x conflicts with Nautobot 1.1-2
-        # Markdown has issues with importlib in newer versions
-        if: "matrix.nautobot-version != '1.3.0'"
-        run: "poetry add markupsafe==2.0.1"
+        if: "matrix.nautobot-version != '1.4.2'"
       - name: "Set Nautobot install to the testing version"
         run: "poetry add nautobot==${{ matrix.nautobot-version }}"
-      - name: "Regenerate Poetry Lock for Older Nautobot Tests"
-        run: "poetry update --lock"
-        if: "matrix.nautobot-version != '1.3.0'"
       - name: "Build Container"
         run: "poetry run invoke build"
       - name: "Run Tests"
@@ -160,6 +147,10 @@ jobs:
         run: "echo RELEASE_VERSION=${GITHUB_REF:10} >> $GITHUB_ENV"
       - name: "Run Poetry Version"
         run: "poetry version $RELEASE_VERSION"
+      - name: "Install Dependencies (needed for mkdocs)"
+        run: "poetry install --no-root"
+      - name: "Build Documentation"
+        run: "poetry run mkdocs build --no-directory-urls --strict"
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Upload binaries to release"
@@ -189,6 +180,10 @@ jobs:
         run: "echo RELEASE_VERSION=${GITHUB_REF:10} >> $GITHUB_ENV"
       - name: "Run Poetry Version"
         run: "poetry version $RELEASE_VERSION"
+      - name: "Install Dependencies (needed for mkdocs)"
+        run: "poetry install --no-root"
+      - name: "Build Documentation"
+        run: "poetry run mkdocs build --no-directory-urls --strict"
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Push to PyPI"

.gitignore

@@ -300,4 +300,7 @@ fabric.properties
 creds.env
 
 # Invoke overrides
-invoke.yml
+invoke.yml
+
+# Static docs
+/nautobot_chatops/static/nautobot_chatops/docs/

.readthedocs.yaml

@@ -0,0 +1,23 @@
+---
+# .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-20.04"
+  tools:
+    python: "3.9"
+
+# MKDocs configuration file
+mkdocs:
+  configuration: "mkdocs.yml"
+  # fail_on_warning: true
+
+# Use our docs/requirements.txt during installation.
+python:
+  install:
+    - requirements: "docs/requirements.txt"

CHANGELOG.md

@@ -1,4 +1,5 @@
-# Changelog - Nautobot Plugin Chatops
+<!-- markdownlint-disable MD024 -->
+# Changelog - Nautobot Plugin ChatOps
 
 ## 1.8.0
 
@@ -53,7 +54,7 @@ Minor update to better handle the versioning. This fixes an issue where the vers
 
 ## v1.4.0
 
-Updates Nautobot Chatops name for Webex Teams to Webex. As part of Cisco's renaming of Webex Teams to just Webex, the underlying configuration was updated.
+Updates Nautobot ChatOps name for Webex Teams to Webex. As part of Cisco's renaming of Webex Teams to just Webex, the underlying configuration was updated.
 
 ### Fixes
 

README.md

@@ -1,29 +1,28 @@
 # nautobot-chatops
 
+![ChatOps Logo](https://raw.githubusercontent.com/nautobot/nautobot-plugin-chatops/develop/docs/assets/icon-ChatOps.png)
+
 A multi-platform ChatOps bot plugin for [Nautobot](https://github.com/nautobot/nautobot).
 
-- Support for multiple chat platforms (currently Slack, Microsoft Teams, and WebEx)
+- Support for multiple chat platforms (currently Slack, Microsoft Teams, Mattermost, and WebEx)
 - Write a command once and run it on every supported platform, including rich content formatting
 - Extensible - other Nautobot plugins can provide additional commands which will be dynamically discovered.
 - Automatic generation of basic help menus (accessed via `help`, `/command help`, or `/command sub-command help`)
 - Metrics of command usage via the `nautobot_capacity_metrics` plugin.
 
 ## Documentation
 
-- [Installation Guide](docs/chat_setup/chat_setup.md)
-- [Design](docs/design.md)
-- [Contributing](docs/contributing.md)
-- [FAQ](docs/FAQ.md)
-
-## Contributing
+Full web-based HTML documentation for this app can be found over on the [Nautobot Docs](https://docs.nautobot.com/projects/chatops/en/latest/) website:
 
-Thank you for your interest in helping to improve Nautobot!
-Refer to the [contributing guidelines](docs/contributing.md) for details.
+- [User Guide](https://docs.nautobot.com/projects/chatops/en/latest/user/app_overview/) - Overview, Using the App, Getting Started
+- [Administrator Guide](https://docs.nautobot.com/projects/chatops/en/latest/admin/admin_install/) - How to Install, Configure, Upgrade, or Uninstall the App.
+- [Developer Guide](https://docs.nautobot.com/projects/chatops/en/latest/dev/dev_contributing/) - Extending the App, Code Reference, Contribution Guide.
+- [Release Notes / Changelog](https://docs.nautobot.com/projects/chatops/en/latest/admin/release_notes/)
+- [Frequently Asked Questions](https://docs.nautobot.com/projects/chatops/en/latest/user/app_faq/)
 
 ## Try it Out
 
-Interested to see Nautobot ChatOps in action?  It's currently setup on the [Demo Instance](https://demo.nautobot.com/) and integrated into [NTC Slack](slack.networktocode.com).  You can sign up for that Slack workspace and join the `#nautobot-chat` channel to understand what this bot can do and try it for yourself.  You can try these exact chat commands and many more:
-
+Interested to see Nautobot ChatOps in action?  It's currently setup on the [Demo Instance](https://demo.nautobot.com/) and integrated into [NTC Slack](https://slack.networktocode.com).  You can sign up for that Slack workspace and join the `#nautobot-chat` channel to understand what this bot can do and try it for yourself.  You can try these exact chat commands and many more:
 
 ### Command: `/nautobot`
 
@@ -33,14 +32,11 @@ Interested to see Nautobot ChatOps in action?  It's currently setup on the [Demo
 
 ![image](https://user-images.githubusercontent.com/6332586/118281772-95239600-b49b-11eb-9c79-e2040dc4a982.png)
 
-
 ### Command: `/nautobot get-interface-connections`
 
-
 ![image](https://user-images.githubusercontent.com/6332586/118281976-ca2fe880-b49b-11eb-87ad-2a41eaa168ed.png)
 
-
 ## Questions
 
-For any questions or comments, please check the [FAQ](docs/FAQ.md) first and feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #nautobot).
-Sign up [here](http://slack.networktocode.com/)
+For any questions or comments, please check the [FAQ](https://docs.nautobot.com/projects/chatops/en/latest/user/app_faq/) first and feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #nautobot).
+Sign up [here](https://slack.networktocode.com/)

development/Dockerfile

@@ -9,6 +9,10 @@ WORKDIR /source
 
 # Copy in only pyproject.toml/poetry.lock to help with caching this layer if no updates to dependencies
 COPY poetry.lock pyproject.toml /source/
+# Pin poetry version to 1.2.0 in older Nautobot Images.
+RUN curl -sSL https://install.python-poetry.org -o /tmp/install-poetry.py && \
+    python /tmp/install-poetry.py --version 1.2.0 && \
+    rm -f /tmp/install-poetry.py
 # --no-root declares not to install the project package since we're wanting to take advantage of caching dependency installation
 # and the project is copied in and installed after this step
 RUN poetry install --no-interaction --no-ansi --no-root

development/docker-compose.dev.yml

@@ -10,6 +10,16 @@ services:
     volumes:
       - "./nautobot_config.py:/opt/nautobot/nautobot_config.py"
       - "../:/source"
+  docs:
+    entrypoint: "mkdocs serve -v -a 0.0.0.0:8080"
+    ports:
+      - "8001:8080"
+    volumes:
+      - "../:/source"
+    image: "nautobot-chatops-plugin/nautobot:${NAUTOBOT_VER}-py${PYTHON_VER}"
+    healthcheck:
+      disable: true
+    tty: true
   worker:
     volumes:
       - "./nautobot_config.py:/opt/nautobot/nautobot_config.py"

docs/chat_setup/chat_setup.md → docs/admin/admin_install.md

@@ -1,131 +1,77 @@
-# Installing Nautobot Chatops
+# Installing the App in Nautobot
+
+There are four main phases to enable Nautobot ChatOps:
 
-There are four main phases to enable Nautobot chatops:
 1. Configure the specific chat platform
 2. Install the plugin
-3. Configure `nautobot_config.py` to support chatops
+3. Configure `nautobot_config.py` to support nautobot-chatops
 4. Grant access to the chatbot in the Nautobot Web UI
 
-## Requirements
-
-* Functioning Nautobot installation
-* Publicly accessible URL for Nautobot or ability/permission to use ngrok to get a publicly accessible URL for Nautobot
-* `sudo` access on the Nautobot server
-* Administrative access within the Nautobot Web UI
-
-> Note: Some chat platforms, such as Slack, require a signed certificate from a trusted provider on the Nautobot server in order 
-> to allow the application platform to communicate with the Nautobot server
-
-## Platform-specific setup
-
-### [Setup for Slack](./slack_setup.md)
+## Prerequisites
 
-### [Setup for Microsoft Teams](./microsoft_teams_setup.md)
+- The plugin is compatible with Nautobot 1.2.0 and higher.
+- Databases supported: PostgreSQL, MySQL
+- Publicly accessible URL for Nautobot or ability/permission to use ngrok to get a publicly accessible URL for Nautobot
+- `sudo` access on the Nautobot server
+- Administrative access within the Nautobot Web UI
 
-### [Setup for WebEx](./webex_setup.md)
+!!! note
+    Some chat platforms, such as Slack, require a signed certificate from a trusted provider on the Nautobot server in order
+    to allow the application platform to communicate with the Nautobot server
 
-### [Setup for Mattermost](./mattermost_setup.md)
+## Access Requirements
 
-## Plug-In Installation
+### [Setup for Slack](slack_setup.md)
 
-The plugin is available as a Python package in PyPI and can be installed with `pip3` after logging in with the `nautobot` user account.
+### [Setup for Microsoft Teams](microsoft_teams_setup.md)
 
-```shell
-sudo -iu nautobot
-pip3 install nautobot-chatops
-```
-
-> The plugin is compatible with Nautobot 1.0.0beta1 and higher
+### [Setup for WebEx](webex_setup.md)
 
-Once installed, the plugin needs to be enabled in your `nautobot_config.py`
+### [Setup for Mattermost](mattermost_setup.md)
 
-```python
-# In your nautobot_config.py
-PLUGINS = ["nautobot_chatops"]
-
-PLUGINS_CONFIG = {
-    "nautobot_chatops": {
-         #     ADD YOUR SETTINGS HERE
-    }
-}
-```
-
-Nautobot supports `Slack`, `MS Teams`, `Mattermost`, and `Webex` as backends but by default all of them are disabled. 
-You need to explicitly enable the chat platform(s) that you want to use in the `PLUGINS_CONFIG` with one or more of `enable_slack`, `enable_ms_teams`, `enable_mattermost`, or `enable_webex`.
-
-The plugin behavior can be controlled with the following list of general settings:
-
-| Configuration Setting        | Description | Mandatory? | Default |
-| ---------------------------- | ----------- | ---------- | ------- |
-| `delete_input_on_submission` | After prompting the user for additional inputs, delete the input prompt from the chat history | No | `False` |
+## Install Guide
 
-TODO: clarify the above statement, starting from "The plugin behavior can be controlled . . ."
+!!! note
+    Plugins can be installed manually or using Python's `pip`. See the [nautobot documentation](https://nautobot.readthedocs.io/en/latest/plugins/#install-the-package) for more details. The pip package name for this plugin is [`nautobot_chatops`](https://pypi.org/project/nautobot_chatops/).
 
-### Run Migrations
+!!! warning
+    You should follow the [Nautobot Plugin Installation Instructions](https://nautobot.readthedocs.io/en/stable/plugins/#installing-plugins) for the full and up-to-date list of instructions.
 
-Once the setup is done, the Nautobot `post_upgrade` command needs to be run. As the _Nautobot user_ (which following Nautobot install docs is `nautobot`) execute:
+The plugin is available as a Python package via PyPI and can be installed with `pip`:
 
-```bash
-nautobot-server post_upgrade
-```
-
-This command runs migrations and clears the cache as necessary.
-
-### Restart Nautobot
-
-As a root user, restart the Nautobot services.
-
-```bash
-systemctl restart nautobot nautobot-worker
+```shell
+pip install nautobot-chatops
 ```
 
-If there is an additional service file for a separate RQ/Celery worker setup, also run:
+To ensure Nautobot Plugin ChatOps is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-chatops` package:
 
-```bash
-systemctl restart nautobot-rq-worker
+```no-highlight
+# echo nautobot-chatops >> local_requirements.txt
 ```
 
-## Server Configuration
-
-As the `nautobot` user, you will now edit the `nautobot_config.py` file.  
-
-There are also some platform-specific requirements to configure.  
-Some values from your chat platform-specific configuration in the prior section are configured in `nautobot_config.py`.
-
-Below is a sample configuration snippet in `nautobot_config.py` that enables Slack. This is meant to serve as a general example of
-how to configure and enable the chatops plugin.
+Once installed, the plugin needs to be enabled in your Nautobot configuration. The following block of code below shows the additional configuration required to be added to your `nautobot_config.py` file:
 
-Note a few details about this example:
-* You must add `"nautobot_chatops"` to the list defined by `PLUGINS`
-* The `slack_api_token` and `slack_signing_secret` values were taken from the values presented in the Slack platform-specific setup.
-* Alternately, the `slack_api_token` and `slack_signing_secret` values could also be stored in an `.env` file, then referred to by those defined environment variables in `PLUGINS_CONFIG`.
-* Some commands can use a user's session cache to keep state for some data between commands (e.g. use the same target device between commands). By default, it keeps data for 86400 seconds, but with `session_cache_timeout` this value can be adjusted.
+- Append `"nautobot_chatops"` to the `PLUGINS` list.
+- Append the `"nautobot_chatops"` dictionary to the `PLUGINS_CONFIG` dictionary and override any defaults.
 
 ```python
-# Enable installed plugins. Add the name of each plugin to the list.
+# In your nautobot_config.py
 PLUGINS = ["nautobot_chatops"]
 
-PLUGINS_CONFIG = {
-    'nautobot_chatops': {
-        'enable_slack': True,
-        'slack_api_token': 'xoxb-2078939598626-2078997105202-3QupQHVC3lEhyGtKPpK62fGB',
-        'slack_signing_secret': '1be5e964569d52a2e74f13fcefb1213f',
-        'session_cache_timeout': 3600,
-    }
-}
+# PLUGINS_CONFIG = {
+#   "nautobot_chatops": {
+#     ADD YOUR SETTINGS HERE
+#   }
+# }
 ```
 
-As a sudo-enabled user, restart the `nautobot` and `nautobot-worker` process after updating `nautobot_config.py`.
+## App Configuration
 
-```
-sudo systemctl restart nautobot.service nautobot-worker.service
-```
+The plugin behavior can be controlled with the following list of settings:
 
-Finally, validate that the `nautobot` and `nautobot-worker` processes have restarted successfully:
-
-```
-sudo systemctl status nautobot.service nautobot-worker.service
-```
+| Configuration Setting        | Description | Mandatory? | Default |
+| ---------------------------- | ----------- | ---------- | ------- |
+| `delete_input_on_submission` | After prompting the user for additional inputs, delete the input prompt from the chat history | No | `False` |
 
 ## Grant Access to the Chatbot
 

docs/admin/admin_uninstall.md

@@ -0,0 +1,18 @@
+# Uninstall the App from Nautobot
+
+## Uninstall Guide
+
+1. Remove Database migrations for ChatOps:
+
+    ```bash
+    nautobot-server migrate nautobot-chatops zero
+    ```
+
+2. Remove the configuration you added in `nautobot_config.py` from `PLUGINS` & `PLUGINS_CONFIG`.
+3. Run Nautobot-server post_upgrade
+
+    ```bash
+    nautobot-server post_ugprade
+    ```
+
+4. Restart Nautobot Services

docs/admin/admin_upgrade.md

@@ -0,0 +1,5 @@
+# Upgrading the App
+
+## Upgrade Guide
+
+When a new release comes out it may be necessary to run a migration of the database to account for any changes in the data models used by this plugin. Execute the command `nautobot-server post_upgrade` from the Nautobot install nautobot/ directory after updating the package.