📝 — Improve documentation (fix #11)

Extra:
- put psycopg2-binary in standard dependencies

Makefile

@@ -28,7 +28,7 @@ pylint: venv ## Runs pylint on the code
 	venv/bin/pylint argos
 pylint-alembic: venv ## Runs pylint on alembic migration files
 	venv/bin/pylint --disable invalid-name,no-member alembic/versions/*.py
-lint: djlint pylint
+lint: djlint pylint pylint-alembic ruff
 help:
 	@python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 

docs/api.md

@@ -10,6 +10,8 @@ To access the API, you need to pass an authentication token in the `Authorizatio
     "Authorization": "Bearer " + token
 ```
 
+See the [CLI documentation](cli.md#server-generate-token-command) to generate tokens.
+
 ## Endpoints
 
 You can also have access to the Swagger API documentation at `https://<argos-url>/docs`, and the ReDoc documentation at `https://<argos-url>/redoc`.

docs/developer/dependencies.md

@@ -0,0 +1,11 @@
+# Installing for development
+
+To install all what you need to develop on Argos, do:
+
+```bash
+git clone https://framagit.org/framasoft/framaspace/argos.git
+cd argos
+make develop
+```
+
+It will create a virtualenv and install all the needed dependencies in it.

docs/developer/tests.md

@@ -0,0 +1,21 @@
+# Tests and linting
+
+## Tests
+
+To launch the tests suite:
+```bash
+make tests
+```
+
+## Linting
+
+There is 4 lintings checks:
+- `make djlint` will check the linting of the HTML templates
+- `make pylint` will check the linting of Argos source code
+- `make pylint-alembic` will check the linting of Alembic’s migrations files
+- `make ruff` will check the linting of all files
+
+You can launch all of them with:
+```bash
+make lint
+```

docs/index.md

@@ -10,33 +10,20 @@ Test how your websites respond to external checks, get notified when something g
 - A **Website** allows to navigate the results of the checks.
 - **HTTP API**: An HTTP API is exposed to get the results of the checks.
 
+![Dashboard](dashboard.jpg)
 
-![Argos web interface](capture.png)
+![Domains list](domains.jpg)
-
-## Installation
-
-```{code-block} bash
-pip install argos-monitoring
-argos server start
-argos agent http://localhost:8000 "<auth-token>"
-```
-
-```{literalinclude} ../config-example.yaml
----
-caption: config.yaml
----
-```
 
 ## Next
 
 ::::{grid} 2
-:::{grid-item-card}  Getting started
+:::{grid-item-card}  Installation
 :link: installation/getting-started.html
 The best way to get started with argos.
 :::
 :::{grid-item-card}  Developper docs
 :link: developer/overview.html
-You want to know more about the internals ?.
+You want to know more about the internals ?
 :::
 ::::
 
@@ -69,9 +56,11 @@ checks
 :caption: Developer docs
 :hidden:
 developer/overview
+developer/dependencies
 developer/new-check
 developer/models
 developer/migrations
+developer/tests
 developer/projects
 changelog
 ```

docs/installation/getting-started.md

@@ -15,17 +15,53 @@ source venv/bin/activate
 pip install -e .
 ```
 
+<!--
+## Install with pip
+
+```bash
+pip install argos-monitoring
+```
+
+You may want to install Argos in a virtualenv:
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install argos-monitoring
+```
+
+## Install from sources
+
+Once you got the source locally, create a virtualenv and install the dependencies:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+-->
+
 ## Configure
 
+### Configure the checks
+
 The quickest way to get started is to copy the `config-example.yaml` file and edit it:
 
 ```bash
 cp config-example.yaml config.yaml
 ```
 
+<!--
+The quickest way to get started is to get the `config-example.yaml` file from our repository and edit it:
+
+```bash
+wget https://framagit.org/framasoft/framaspace/argos/-/raw/main/config-example.yaml -O config.yaml
+```
+-->
+
 You can read more about the configuration in the [configuration section](../configuration.md).
 
-## Starting the server
+### Configure the server
 
 Environment variables are used to configure the server. You can also put them in an `.env` file:
 
@@ -37,6 +73,8 @@ caption: .env
 
 Please note that the only supported database engines are SQLite for development and PostgreSQL for production.
 
+## Starting the server
+
 Then you can start the server:
 
 ```bash
@@ -45,12 +83,30 @@ argos server start
 
 The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration. 
 
+## Generating a token 
+
+The agent needs an authentication token to be able to communicate with the server.
+
+You can generate an authentication token with the following command:
+```bash
+argos server generate-token
+```
+
+Add the token in the configuration file, in the following setting:
+
+```yaml
+service:
+  secrets:
+    - "auth-token"
+```
+
 ## Running 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.
+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>"
+argos agent http://localhost:8000 "auth-token"
 ```
 
 ## Cleaning the database
@@ -61,6 +117,6 @@ Here is a crontab example, which will clean the db each hour:
 
 ```bash
 # Run the cleaning tasks every hour (at minute 7)
-# Keeps 10 results per task, and locks the tasks for 1 hour
+# Keeps 10 results per task, and remove tasks’ locks older than 1 hour
 7 * * * * argos server cleandb --max-results 10 --max-lock-seconds 3600
 ```

docs/installation/postgresql.md

@@ -1,10 +1,4 @@
-# Use with PostgreSQL
+# Install and configure PostgreSQL
-
-If you intend to use argos with Postgresql, which is recommended for production, you can install it with the following commands:
-
-```bash
-pip install -e ".[postgres]"
-```
 
 Here are a few steps for you to install PostgreSQL on your system:
 

pyproject.toml

@@ -20,8 +20,10 @@ dependencies = [
   "alembic>=1.13.0,<1.14",
   "click>=8.1,<9",
   "fastapi>=0.103,<0.104",
+  "gunicorn>=21.2,<22",
   "httpx>=0.25,<1",
   "Jinja2>=3.0,<4",
+  "psycopg2-binary>=2.9,<3",
   "pydantic[email]>=2.4,<3",
   "pydantic-settings>=2.0,<3",
   "pyyaml>=6.0,<7",
@@ -30,7 +32,6 @@ dependencies = [
   "sqlalchemy-utils>=0.41,<1",
   "tenacity>=8.2,<9",
   "uvicorn>=0.23,<1",
-  "gunicorn>=21.2,<22",
 ]
 
 [project.optional-dependencies]
@@ -47,9 +48,6 @@ dev = [
   "ruff==0.1.5,<1",
   "sphinx-autobuild",
 ]
-postgres = [
-  "psycopg2-binary>=2.9,<3",
-]
 docs = [
   "cogapp", 
   "myst-parser>=2.0,<3",