Add doc file designed to be used to reference the plugin on the Woodpecker CI website

docs.md

@@ -0,0 +1,65 @@
+---
+name: Aptly
+icon: https://www.aptly.info/img/logo.svg
+description: plugin to publish Debian package on a Aptly repository
+authors: Benjamin Renard
+tags: [APT, aptly, publish]
+containerImage: brenard/aptly-publish
+containerImageUrl: https://hub.docker.com/r/brenard/aptly-publish
+url: https://gitea.zionetrix.net/bn8/aptly-publish
+---
+
+Woodpecker CI plugin to publish one (or more) Debian package on a Aptly repository using its API.
+
+## Features
+
+This plugin will try to :
+- List all changes files in the specified directory and filter on the specified source package name (if specified)
+- Iter on detected changes files and foreach of then:
+ - the changes file is parsed to detect the source package name, the distribution and included files
+ - the repository name is computed (if not specified). __Format:__ `{prefix}_{distribution}_{component}`. __Note:__ if the default prefix is specified (`.`), it will not be used to compute the repository name.
+ - the current published distribution is retreived using APTLY Publish API to:
+   - check it was already manally published a first time
+   - check it used a snapshot kind of sources
+   - retreive other components source snapshot
+ - Upload the changes file and all its included files using APTLY File Upload API in a directory named as the source package
+ - Include the changes file using APTLY Local Repos API
+ - Compute a snapshot name for the repository based on the current date and the repository name. __Format:__ `YYYYMMDD-HHMMSS_{repository name}`
+ - Create a snapshot of the repository using APTLY Local Repos API
+ - Update the published distribution with this new snapshot as source of the specified component and keeping other components source snapshot.
+
+In case of error, it will exit with a detailed error message (within the limits of what is provided by the Aptly API).
+
+## Settings
+
+| Settings Name             | Default           | Description
+| --------------------------| ----------------- | --------------------------------------------
+| `api_url`                 | *none*            | Your Aptly API URL (required)
+| `api_username`            | *none*            | Username to authenticate on your Aptly API (required)
+| `api_password`            | *none*            | Password to authenticate on your Aptly API (required)
+| `prefix`                  | `.`               | The publishing prefix
+| `repo_component`          | `main`            | The component name to publish on
+| `repo_name`               | `{prefix}_{distribution}_{component}` | The repository name to publish on. If not specified, it will be computed using the specified prefix and component and the detected package distribution. See above for details.
+| `path`                    | `dist`            | Path to the directory where files to publish are stored
+| `source_name`             | *none*            | Name of the source package to publish (optional, default: all `changes` files are will be publish)
+| `max_retries`             | *none*            | The number of retry in case of error calling the Aptly API (optional, default: no retry)
+
+
+## Example
+
+```yaml
+pipeline:
+  publish:
+    image: brenard/aptly-publish
+    settings:
+      api_url: https://your.aptly.tld/api
+      api_username: myproject
+      api_password:
+        from_secret: aptly_api_password
+      prefix: debian
+      repo_component: main
+      repo_name: debian_stable_main
+      path: dist
+      source_name: myproject
+      max_retries: 2
+```