Add some more documentation

docs/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/repository.html

@@ -0,0 +1,8 @@
+<a class="js-repo-stats repo-stats flex items-center" href="https://framagit.org/framasoft/framaspace/argos/">
+  <span class="w-8 flex items-center justify-around shrink-0 text-2xl">
+    <i class="i-icon gitlab"></i>
+  </span>
+  <span class="flex-grow px-2">
+    <span>framasoft/argos</span>
+  </span>
+</a>

docs/checks.md

@@ -2,8 +2,44 @@
 
 At its core, argos runs checks and return the results to the service. Here are the implemented checks, with a description of what they do and how to configure them.
 
+## Simple checks
+
+These checks are the most basic ones. They simply check that the response from the service matches what you expect.
+
 | Check | Description | Configuration |
 | --- | --- | --- |
 | `status-is` | Check that the returned status code matches what you expect. | `status-is: "200"` |
 | `body-contains` | Check that the returned body contains a given string. | `body-contains: "Hello world"` |
-| `ssl-certificate-expiration` | Check that the SSL certificate expires in more than X days. | `ssl-certificate-expiration: "30d"` |
+
+```{code-block} yaml
+---
+caption: config.yaml
+---
+- domain: "https://example.org"
+  paths:
+    - path: "/"
+      checks:
+        - status-is: 200
+        - body-contains: "Hello world"
+```
+
+## SSL certificate expiration
+
+ Checks that the SSL certificate will not expire soon. You need to define the thresholds in the configuration, and set the `on-check` option to enable the check.
+
+
+```{code-block} yaml
+---
+caption: config.yaml
+---
+ssl:
+  thresholds:
+    - "1d": critical
+    - "5d": warning
+
+- domain: "https://example.org"
+  paths:
+    - path: "/"
+      checks:
+        - ssl-certificate-expiration: "on-check"
+```

docs/conf.py

@@ -14,15 +14,19 @@ release = "0.0.1"
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = [
+extensions = ["myst_parser", "sphinx_design", "sphinxcontrib.mermaid"]
-    "myst_parser",
-    "sphinx_design",
-]
 myst_enable_extensions = ["colon_fence"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+mermaid_params = ['--theme', 'forest']
 
+html_sidebars = {
+    "**": [
+        "sidebars/localtoc.html",
+        "repository.html",
+    ]
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/configuration.md

@@ -13,6 +13,7 @@ caption: .env
 ---
 ```
 
+
 ## Checks configuration
 
 Argos uses a YAML configuration file to define the websites to monitor and the checks to run on these websites.

docs/developer/models.md

@@ -0,0 +1,33 @@
+# The data model
+
+```{mermaid}
+classDiagram
+direction RL
+Task *-- Result : Have many
+Task: id
+Task: url
+Task: domain
+Task: check
+Task: expected
+Task: frequency
+Task: selected_by
+Task: selected_at
+Task: completed_at
+Task: next_run
+
+Result: id
+Result: task_id
+Result: task
+Result: agent_id
+Result: submitted_at
+Result: status
+Result: severity
+Result: context
+```
+
+
+```{literalinclude} ../../argos/server/models.py
+---
+caption: models.py
+---
+```

docs/developer/new-check.md

@@ -0,0 +1,40 @@
+# Implementing a new check
+
+## Creating a new check class
+
+If you want to implement a new check, you need to create a new class that inherits from `argos.checks.BaseCheck`.
+
+You need to implement two methods, and specify the type of the data you want to check.
+
+Let's create a new check that ensures that the specified header is present.
+
+```python
+class HeaderExists(BaseCheck):
+    """Checks that the response contains the specified header."""
+
+    config = "header-exists"
+    expected_cls = ExpectedStringValue
+
+    async def run(self):
+        response = await self.http_client.head(self.task.url)
+        result = (self.expected.value in response.headers)
+
+        return self.response(status=result)
+```
+
+## Using configuration values to determine the severity
+
+The agents don't have access to the configuration values, so they can't determine the severity of the check, albeit in some case that could be useful.
+
+If that's your case, you can implement the `finalize` method, and return some extra values in the `run` method, like this:
+
+```python
+    async def run(self):
+            # ... see earlier example
+            return self.response(status=result, extra_arg="extra_value")
+
+    @classmethod
+    async def finalize(cls, config, result, extra_arg):
+        # You can use the extra_arg here to determine the severity
+        return Status.SUCCESS, Severity.OK
+```

docs/developer/overview.md

@@ -0,0 +1,29 @@
+# Technical overview
+
+Argos uses an agent and server architecture. The server is responsible for storing the configuration and the results of the checks. The agent is responsible for running the checks and sending the results to the server.
+
+## Sequence diagram
+
+```{mermaid}
+sequenceDiagram
+    participant Agent
+    participant Server
+    loop
+        Agent->>Server: Hey, do you have some work for me?
+        Server-->>Agent: Here is some work
+        Agent->>Agent: Run checks
+        Agent->>Server: Here are the results
+        Server->>Server: Determine severity
+        Server->>Server: Store results
+    end
+```
+
+## Orchestration
+
+The server acts like a job queue. When an agent asks for work, the server will:
+- mark the tasks as "selected by" the agent
+- store the current date
+  
+When it receives the results, it will:
+- Remove the "selected by" and "selected at" fields
+- Compute the next execution date.

docs/index.md

@@ -47,13 +47,21 @@ You want to know more about the internals ?.
 
 installation/getting-started
 installation/postgresql
-configuration
 cli
 ```
 
 ```{toctree}
-:caption: Checks
+:caption: Configuration
 :hidden:
-
+configuration
 checks
+```
+
+```{toctree}
+:caption: Developer docs
+:hidden:
+developer/overview
+developer/new-check
+developer/models
+
 ```

pyproject.toml

@@ -50,6 +50,7 @@ docs = [
   "shibuya",
   "sphinx-design",
   "cogapp", 
+  "sphinxcontrib-mermaid>=0.9,<1",
 ]
 
 [project.urls]