Fix broken links and update docs

Makefile

@@ -1,10 +1,40 @@
-venv:
+.DEFAULT_GOAL := help
+RED=\033[0;31m
+GREEN=\033[0;32m
+ORANGE=\033[0;33m
+BLUE=\033[0;34m
+NC=\033[0m # No Color
+
+venv: ## Create the venv
 	python3 -m venv venv
-install: venv
+install: venv ## Install the project locally
 	venv/bin/pip install -e ".[dev,docs]"
-docs: cog
+docs: cog ## Build the docs
 	venv/bin/sphinx-build docs public
-cog:
+cog: ## Run cog, to integrate the CLI options to the docs.
 	venv/bin/cog -r docs/*.md
-tests: install
+tests: install ## Run the tests
 	venv/bin/pytest
+
+help:
+	@python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
+
+# See https://daniel.feldroy.com/posts/autodocumenting-makefiles
+define PRINT_HELP_PYSCRIPT # start of Python section
+import re, sys
+
+output = []
+# Loop through the lines in this file
+for line in sys.stdin:
+    # if the line has a command and a comment start with
+    #   two pound signs, add it to the output
+    match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
+    if match:
+        target, help = match.groups()
+        output.append("\033[36m%-25s\033[0m %s" % (target, help))
+# Sort the output in alphanumeric order
+output.sort()
+# Print the help result
+print('\n'.join(output))
+endef
+export PRINT_HELP_PYSCRIPT # End of python section

README.md

@@ -1,6 +1,6 @@
 # Argos monitoring
 
-An HTTP monitoring service.
+A monitoring and status board for your websites.
 
 1. Define a list of websites to monitor
 2. Specify a list of checks to run on these websites.

docs/index.md

@@ -1,21 +1,18 @@
 # Argos monitoring
 
-Argos is an HTTP monitoring service.
+A monitoring and status board for websites.
-
+Test how your websites respond to external checks, get notified when something goes wrong.
-1. Define a list of websites to monitor
-2. Specify a list of checks to run on these websites.
-3. Argos will run the checks periodically and alert you if something goes wrong.
-
-Internally, a HTTP API is exposed, and a job queue is used to distribute the checks on the network.
 
 ## Features
 
-- **Made for large systems**: It's meant to supervise a large number of websites.
+- **Server-Agent 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.
-- **Server/Agent 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.
+- **Extensibility**: New checks can be added using python.
-- **Extensible**: You can add new checks using pure python.
+- A **Website** allows to navigate the results of the checks.
-- **HTTP API**: You can use the HTTP API to get the results of the checks.
+- **HTTP API**: An HTTP API is exposed to get the results of the checks.
+
+
+![Argos web interface](capture.png)
 
-![Argos architecture](capture.png)
 ## Installation
 
 ```{code-block} bash
@@ -38,7 +35,7 @@ caption: config.yaml
 The best way to get started with argos.
 :::
 :::{grid-item-card}  Developper docs
-:link: /developer/overview.html
+:link: developer/overview.html
 You want to know more about the internals ?.
 :::
 ::::

docs/installation/getting-started.md

@@ -1,7 +1,5 @@
 # Installation
 
-So, you want to get started :-) Nothing complicated here, but here is a step by step guide.
-
 ## Requirements
 
 - Python 3.11+
@@ -19,7 +17,7 @@ pip install -e .
 
 ## Configure
 
-Prepare a configuration file, you can copy the `config-example.yaml` file and edit it:
+The quickest way to get started is to copy the `config-example.yaml` file and edit it:
 
 ```bash
 cp config-example.yaml config.yaml
@@ -29,7 +27,7 @@ You can read more about the configuration in the [configuration section](configu
 
 ## Starting the server
 
-You need to specify environment variables to configure the server, or you can put them in an `.env` file:
+Environment variables are used to configure the server. You can also put them in an `.env` file:
 
 ```{literalinclude} ../../.env.example
 ---
@@ -43,11 +41,11 @@ Then you can start the server:
 argos server start
 ```
 
-The server will read a `yaml` file at startup, and will populate the tasks specified in it. 
+The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration. 
 
 ## Running the agent
 
-And here is how to run the agent:
+You can run the agent on the same machine as the server, or on a different machine. The only requirement is that the agent can reach the server.
 
 ```bash
 argos agent http://localhost:8000 "<auth-token>"
@@ -55,11 +53,12 @@ argos agent http://localhost:8000 "<auth-token>"
 
 ## Running cleaning tasks
 
-You also need to run cleaning tasks periodically. `argos server clean --help` will give you more information on how to do that.
+You also have to run cleaning tasks periodically. `argos server clean --help` will give you more information on how to do that.
 
 Here is a crontab example:
 
 ```bash
 # Run the cleaning tasks every hour (at minute 7)
-7 * * * * argos server clean --max-results 100000 --max-lock-seconds 3600
+# Keeps the last 100000 results, and locks the tasks for 1 hour
+7 * * * * argos server cleandb --max-results 100000 --max-lock-seconds 3600
 ```