From ff275ea442fc229b549663325419e103abbbbfcb Mon Sep 17 00:00:00 2001 From: Hanne Moa Date: Tue, 29 Mar 2022 08:16:30 +0200 Subject: [PATCH 1/4] Fix pre-commit exclude to preserve docs/conf.py Turns out we had misunderstood how pre-commit excludes files. When running at least "black" from pre-commit, black doesn't use its own config files at all, including any list of excluded files. --- .pre-commit-config.yaml | 2 +- docs/conf.py | 1 + pyproject.toml | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ed781ce56..a1dddf6a0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,7 +18,7 @@ repos: rev: 24.8.0 hooks: - id: black - exclude: migrations/ + exclude: ^(src/.*/migrations|docs/conf.py) - repo: https://github.com/twisted/towncrier rev: 24.8.0 hooks: diff --git a/docs/conf.py b/docs/conf.py index a723a4f9f..b5d583a72 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,6 +50,7 @@ "sphinx.ext.autodoc", "sphinx.ext.todo", "sphinx.ext.coverage", + 'sphinx.ext.graphviz', "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "djangodocs", diff --git a/pyproject.toml b/pyproject.toml index 2e948b5ad..2a4ba3c33 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -102,6 +102,7 @@ exclude = ''' | buck-out | build | dist + | docs/conf.py )/ | src/.*/migrations ) From dde28cd099df1eca2ab651a2b4c331a1b6bd5dca Mon Sep 17 00:00:00 2001 From: Hanne Moa Date: Tue, 29 Mar 2022 08:25:04 +0200 Subject: [PATCH 2/4] Add developer overview to docs --- docs/development.rst | 1 + docs/development/birdseye-view.dot | 32 +++++++++++++++ docs/development/birdseye-view.rst | 65 ++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+) create mode 100644 docs/development/birdseye-view.dot create mode 100644 docs/development/birdseye-view.rst diff --git a/docs/development.rst b/docs/development.rst index babbd91bb..6713d97d7 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,6 +5,7 @@ Development .. toctree:: + development/birdseye-view development/notes development/management-commands development/howtos diff --git a/docs/development/birdseye-view.dot b/docs/development/birdseye-view.dot new file mode 100644 index 000000000..663ea4332 --- /dev/null +++ b/docs/development/birdseye-view.dot @@ -0,0 +1,32 @@ +digraph overview { + compound=true; + + subgraph cluster_server { + style = rounded; + label = "server" + destination1[label="destination 1"]; + destination2[label="destination 2"]; + destination3[label="destination 3"]; + } + + glueservice1[label="glue service 1"]; + source1[label="source 1"]; + + source1 -> glueservice1 -> destination2 [lhead=cluster_server]; + + subgraph cluster_source2 { + style = rounded; + label = "source 2" + glueservice2[label="glue service 2"]; + } + + glueservice2 -> destination2 [lhead=cluster_server]; + + exterior1[shape="none"][style="invis"][label=""]; + exterior2[shape="none"][style="invis"][label=""]; + exterior3[shape="none"][style="invis"][label=""]; + + destination1 -> exterior1; + destination2 -> exterior2; + destination3 -> exterior3; +} diff --git a/docs/development/birdseye-view.rst b/docs/development/birdseye-view.rst new file mode 100644 index 000000000..b671c3ef5 --- /dev/null +++ b/docs/development/birdseye-view.rst @@ -0,0 +1,65 @@ +================= +A bird's eye view +================= + +.. graphviz:: birdseye-view.dot + +Sources +======= + +A source pushes incidents to the argus server via the API. Changes to those +incidents are done via pushing events. An incident has a field +``incident_source_id`` for storing an id, for changing an already existing +incident by adding an event. + +Glue-service +------------ + +A glue-service runs independently of argus server. It sits between a source and +the argus server and translates an incident from the source to the API. The +``incident_source_id`` for the incident is copied from the source if available +or otherwise handled by the glue-service. + +The glue-service can either be built in to the source, or be completely +standalone and pull changes from the source before it pushes them on. + +Agent +----- + +An agent can change existing incidents (by adding events) or create new +incidents by analyzing already existing incidents and events. + +It is standalone. + +Frontend +======== + +The frontend fetches a list of incidents according to a user-created filter. It +allows the user to create such filters, to set up notification profiles +using these filters, and to set up destinations to be used in the profiles. + +Notification system +=================== + +A user has one or more notification profiles. + +A notification profile is used by the server for sending notifications about +a chosen subset of the incidents. It consists of one or more filters, one or +more timeslots (for which periods of the day a profile is valid) and one or +more destinations. + +Destination +----------- + +A destination is a plugin to argus server. It stores its config in the +"DestinationConfig"-model. See :doc:`/writing-plugins`. + +Server +====== + +The server receives incidents from sources, provides access to the accumulated +list of incidents via API, and matches incidents to notification profiles. +Matched incidents are sent to the destinations listed in the profiles. + +There is a non-API admin-interface for the registration of sources and admin +users. From 953f9747ccd9242a4af033585958c9cc041e27bc Mon Sep 17 00:00:00 2001 From: Hanne Moa Date: Mon, 25 Apr 2022 14:03:10 +0200 Subject: [PATCH 3/4] Fix typo in docs/development/birdseye-view.rst Co-authored-by: Morten Brekkevold <100995+lunkwill42@users.noreply.github.com> --- docs/development/birdseye-view.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/birdseye-view.rst b/docs/development/birdseye-view.rst index b671c3ef5..3b4f0b2cd 100644 --- a/docs/development/birdseye-view.rst +++ b/docs/development/birdseye-view.rst @@ -15,8 +15,8 @@ incident by adding an event. Glue-service ------------ -A glue-service runs independently of argus server. It sits between a source and -the argus server and translates an incident from the source to the API. The +A glue-service runs independently of the argus server. It sits between a source +and the argus server and translates an incident from the source to the API. The ``incident_source_id`` for the incident is copied from the source if available or otherwise handled by the glue-service. From e24ca28ed24032e54b55197fcd95b056f35a9da1 Mon Sep 17 00:00:00 2001 From: Hanne Moa Date: Mon, 25 Apr 2022 14:04:01 +0200 Subject: [PATCH 4/4] Update verb choice in docs/development/birdseye-view.rst Co-authored-by: Morten Brekkevold <100995+lunkwill42@users.noreply.github.com> --- docs/development/birdseye-view.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/birdseye-view.rst b/docs/development/birdseye-view.rst index 3b4f0b2cd..66688ecfb 100644 --- a/docs/development/birdseye-view.rst +++ b/docs/development/birdseye-view.rst @@ -7,8 +7,8 @@ A bird's eye view Sources ======= -A source pushes incidents to the argus server via the API. Changes to those -incidents are done via pushing events. An incident has a field +A source pushes incidents to the argus server via the API. Subsequent changes +to those incidents are made by posting events to them. An incident has a field ``incident_source_id`` for storing an id, for changing an already existing incident by adding an event.