From fc0a385027caae73f4a7bafdfba3652a7af2205f Mon Sep 17 00:00:00 2001
From: Goffi <goffi@goffi.org>
Date: Tue, 3 Nov 2026 14:24:59 +0100
Subject: [PATCH] doc (components): document the common component settings:

- Move the `ComponentSettings` autodoc from "Simplified Component Configuration" to a new
  "Common Component Settings" section. This was confusing when most of time only `jid` and
  `secret` are needed.
- Document the config section naming (dashes replaced by underscores) and how to run a
  component in an isolated instance (systemd, `li -i`).
- Fix the `[components.X]` section names (`[component.X]`).
---
 doc/components.rst | 53 ++++++++++++++++++++++++++++++----------------
 1 file changed, 35 insertions(+), 18 deletions(-)

diff --git a/doc/components.rst b/doc/components.rst
index 4611faf4..dc3d99a8 100644
--- a/doc/components.rst
+++ b/doc/components.rst
@@ -1,8 +1,8 @@
 .. _components:
 
-===================
-Libervia Components
-===================
+==========
+Components
+==========
 
 Libervia can act as an XMPP server component, which can be seen as a generic plugin for
 XMPP servers.
@@ -38,23 +38,20 @@ OpenFire
 Prosody
   https://prosody.im/doc/components
 
-Tigase
-  https://docs.tigase.net/en/latest/Tigase_Administration/Components/_Components.html#external-component-configuration
+.. Tigase documentation is down (2026-11-03, the whole docs.tigase.net site is 404),
+   uncomment once it's back:
+.. Tigase
+..   https://docs.tigase.net/en/latest/Tigase_Administration/Components/_Components.html#external-component-configuration
 
 Simplified Component Configuration
 ==================================
 
 Most user will want to use this simplified configuration. To set up a component, you
-simply need to create a configuration section with ``[component.<entry_point>]`` where
-you'll set the ``jid`` and ``secret`` options. Everything will be automatically configured
-on backend startup, and the component will start automatically.
-
-settings
---------
-
-In ``[component.<entry_point>]``:
-
-.. autopydantic_settings:: libervia.backend.tools.config.ComponentSettings
+simply need to create a configuration section named after the entry point, with dashes
+replaced by underscores (e.g. the ``email-gateway`` entry point uses the
+``[component.email_gateway]`` section), where you'll set the ``jid`` and ``secret``
+options. Everything will be automatically configured on backend startup, and the
+component will start automatically.
 
 example
 -------
@@ -69,6 +66,10 @@ find that it's ``pubsub``, then you simply put in your configuration (usually
   jid = "pubsub.example.org"
   secret = "your_shared_secret"
 
+To run the component in an isolated backend instance (e.g. as a dedicated systemd
+service), see :ref:`installation_system`. To work with such an instance from the CLI,
+use the ``-i/--isolation`` option (see :ref:`li_isolation`).
+
 Manual Component Configuration
 ==============================
 
@@ -108,6 +109,14 @@ wants to connect it immediately, she can use::
 
   $ li profile connect -cp ap-gateway
 
+Common Component Settings
+=========================
+
+Besides component specific options (see the component sections below), every
+component supports these common options in its configuration section:
+
+.. autopydantic_settings:: libervia.backend.tools.config.ComponentSettings
+
 Available Components
 ====================
 
@@ -139,7 +148,7 @@ entities (JIDs). Permissions can be set through Ad-Hoc Commands.
 Configuration
 ~~~~~~~~~~~~~
 
-All options are to be set in ``[components.file_sharing]`` section.
+All options are to be set in ``[component.file_sharing]`` section.
 
 ``http_upload_port``
   port to use for HTTP File Upload
@@ -216,7 +225,13 @@ documentation to find how this must be done.
 Configuration
 ~~~~~~~~~~~~~
 
-All options are to be set in ``[components.ap_gateway]`` section.
+All options are to be set in ``[component.ap_gateway]`` section:
+
+.. autopydantic_settings:: libervia.backend.plugins.plugin_comp_ap_gateway.settings.APGatewaySettings
+
+By default, the HTTP server uses HTTPS, thus a TLS certificate is required, either in the
+``tls`` option or in the global ``[tls]`` section. If an HTTPS proxy already handles TLS,
+use ``http_connection_type = "http"`` instead.
 
 .. _ap-actor-from-xmpp:
 
@@ -745,7 +760,7 @@ any kind of extra informations) while AP only indicates if one will attend or no
 event.
 
 
-.. _Mobilizon: https://joinmobilizon.org/
+.. _Mobilizon: https://mobilizon.org/
 
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -812,6 +827,8 @@ All options are to be set in the ``[component.conferences]`` section.
 .. _Galène project: https://galene.org/
 
 
+.. _email-gateway:
+
 Email Gateway
 -------------