From 1a9c08c93feb2903a1fdf2bfc3378d383a9d3e03 Mon Sep 17 00:00:00 2001
From: "Antoine R. Dumont (@ardumont)" <ardumont@softwareheritage.org>
Date: Wed, 6 Oct 2021 18:42:20 +0200
Subject: [PATCH] docs: Add a save forge documentation

This does not yet enter into the registration of a new lister.

Related to T3629
---
 docs/index.rst      |  1 +
 docs/save_forge.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/save_forge.rst

diff --git a/docs/index.rst b/docs/index.rst
index 116b84b..4f6a4b3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,6 +19,7 @@ Overview
 
    tutorial
    run_a_new_lister
+   save_forge
 
 
 Reference Documentation
diff --git a/docs/save_forge.rst b/docs/save_forge.rst
new file mode 100644
index 0000000..8c4e5f6
--- /dev/null
+++ b/docs/save_forge.rst
@@ -0,0 +1,51 @@
+.. _save-forge:
+
+Save a forge
+============
+
+Assuming the forge's :ref:`listing type is already supported in the
+scheduler<register-task-type>`, use ``swh scheduler task add`` command:
+
+::
+
+   swh scheduler --config-file /etc/softwareheritage/scheduler.yml \
+     task add [--policy [recurring|oneshot]] <task-type> [param1=value1] [param2=value2]
+
+For example:
+
+-  To add a task requiring no parameters (launchpad lister)
+
+::
+
+   $ swh scheduler --config-file /etc/softwareheritage/scheduler.yml \
+     task add list-launchpad-full
+   INFO:swh.core.config:Loading config file /etc/softwareheritage/scheduler.yml
+   Created 1 tasks
+
+   Task 1240540
+     Next run: just now (2020-09-08 13:08:07+00:00)
+     Interval: 90 days, 0:00:00
+     Type: list-launchpad-full
+     Policy: recurring
+     Args:
+     Keyword args:
+
+-  To add a one-shot task with parameters:
+
+::
+
+   $ swh scheduler --config-file /etc/softwareheritage/scheduler.yml \
+     task add --policy oneshot \
+     list-gitea-full url=https://codeberg.org/api/v1/ limit=100
+   INFO:swh.core.config:Loading config file /etc/softwareheritage/scheduler.yml
+   Created 1 tasks
+
+   Task 1240540
+     Next run: just now (2020-09-11 14:25:45+00:00)
+     Interval: 90 days, 0:00:00
+     Type: list-gitea-full
+     Policy: oneshot
+     Args:
+     Keyword args:
+       limit: 100
+       url: 'https://codeberg.org/api/v1/'