Restructure integrations documentation

Uninett · Dec 4, 2023 · 863067a · 863067a
1 parent 70a2841
commit 863067a
Show file tree

Hide file tree

Showing 11 changed files with 51 additions and 18 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,11 +14,8 @@ Welcome to Argus' documentation!
    api
    site-specific-settings
    authentication
-   notifications
-   ticket-systems
+   integrations/index
    development
-   integrating-monitoring-systems
-   writing-glueservices
    :maxdepth: 2
    :caption: Contents:
 

diff --git a/docs/integrating-monitoring-systems.rst → docs/integrations/glue-services/index.rst b/docs/integrating-monitoring-systems.rst → docs/integrations/glue-services/index.rst
@@ -28,14 +28,6 @@ Existing glue services
 * Network Administration Visualized: https://github.com/Uninett/nav-argus-glue
 
 
-Writing your own glue service
------------------------------
-
-If there is no pre-existing glue service software for your particular
-monitoring system, we've provided a :doc:`guide for writing your own
-<writing-glueservices>`.
-
-
 Integrating an existing monitoring system
 =========================================
 
@@ -81,3 +73,13 @@ the Argus API server, reachable at
 
      If a token is not valid it will currently lead to the source system
      not being able to report incidents without any warnings.
+
+Writing your own glue service
+=============================
+
+If there is no pre-existing glue service software for your particular
+monitoring system, we've provided a :doc:`guide for writing your own
+<writing-glueservices>`.
+
+.. toctree::
+   writing-glueservices
diff --git a/docs/writing-glueservices.rst → ...ns/glue-services/writing-glueservices.rst b/docs/writing-glueservices.rst → ...ns/glue-services/writing-glueservices.rst
diff --git a/docs/integrations/index.rst b/docs/integrations/index.rst
@@ -0,0 +1,34 @@
+.. Argus documentation master file, created by
+   sphinx-quickstart on Fri Apr 24 09:29:51 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+============
+Integrations
+============
+
+Argus can integrate with monitoring systems via external glue services. It can
+integrate with ticket systems via ticket plugins, and with notification systems
+via notification plugins.
+
+In short:
+
+* Monitoring systems send their alerts via a *glue service*. Either via an
+  argus-plugin (nav) or a standalone microservice (nagios). The service is
+  registered in Argus with a source type and a source, which allows multiple
+  entries from the same type. The source has a token connected with it, which
+  the service uses to authenticate.
+* Notification systems are hooked up via plugins. The plugins are installed (via
+  pip) to the same path as argus. Most plugins are configured solely via the
+  web interface, except for the two included email-based plugins. These piggy
+  back on the email server configuration of argus itself.
+* A single ticket system is hooked up via a plugin. It is installed (via pip)
+  to the same path as argus. All ticket system plugins are configured via the
+  admin.
+
+.. toctree::
+   glue-services/index
+   notifications/index
+   ticket-systems/index
+   :maxdepth: 2
+   :caption: Contents:
diff --git a/docs/notifications/email-plugin.rst → ...tegrations/notifications/email-plugin.rst b/docs/notifications/email-plugin.rst → ...tegrations/notifications/email-plugin.rst
@@ -34,4 +34,4 @@ This email can be copied and a destination with that email address can be
 created in Argus and added to notification profiles.
 
 More information about this can be found on the
-`Slack help website <https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V>`_.
+`Slack help website <https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V>`_.
diff --git a/docs/notifications.rst → docs/integrations/notifications/index.rst b/docs/notifications.rst → docs/integrations/notifications/index.rst
@@ -21,8 +21,8 @@ Notification plugins included on install
 ----------------------------------------
 
 .. toctree::
-   notifications/email-plugin
-   notifications/sms-plugin
+   email-plugin
+   sms-plugin
 
 Other notification plugins
 --------------------------
@@ -41,4 +41,4 @@ Writing your own notification plugins
 -------------------------------------
 
 .. toctree::
-   notifications/writing-notification-plugins
+   writing-notification-plugins
diff --git a/docs/notifications/sms-plugin.rst → ...integrations/notifications/sms-plugin.rst b/docs/notifications/sms-plugin.rst → ...integrations/notifications/sms-plugin.rst
diff --git a/...ications/writing-notification-plugins.rst → ...ications/writing-notification-plugins.rst b/...ications/writing-notification-plugins.rst → ...ications/writing-notification-plugins.rst
diff --git a/docs/ticket-systems.rst → docs/integrations/ticket-systems/index.rst b/docs/ticket-systems.rst → docs/integrations/ticket-systems/index.rst
@@ -5,8 +5,8 @@ Ticket systems
 ==============
 
 .. toctree::
-   ticket-systems/settings
-   ticket-systems/writing-ticket-system-plugins
+   settings
+   writing-ticket-system-plugins
 
 It is possible to automatically create a ticket from an Argus incident with
 a pre-filled title and body.

diff --git a/docs/ticket-systems/settings.rst → .../integrations/ticket-systems/settings.rst b/docs/ticket-systems/settings.rst → .../integrations/ticket-systems/settings.rst
diff --git a/...systems/writing-ticket-system-plugins.rst → ...systems/writing-ticket-system-plugins.rst b/...systems/writing-ticket-system-plugins.rst → ...systems/writing-ticket-system-plugins.rst