Add basic documentation built with Docusaurus

We also:

- Add a new menu and rewrite the contribute page;
- Add readthedoc configuration file;
- Move page markdown page on specific folder

Signed-off-by: Pierrick Chovelon <pierrick.chovelon@dalibo.com>

Author: pchovelon

REUSE.toml

@@ -12,6 +12,7 @@ path = [
     "PROJECT",
     "manifest.yaml",
     "config/**",
+    "docs/**",
     "examples/**",
     "kubernetes/**",
     ".github/workflows/**",

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    nodejs: "22"
+
+  commands:
+    # Install Docusaurus dependencies
+    - cd docs/ && npm install
+    # Build the site
+    - cd docs/ && npm run build
+    # Copy generated files into Read the Docs directory
+    - mkdir --parents $READTHEDOCS_OUTPUT/html/
+    - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/
+        
+
+

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/backup.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 5
+---
+
+# Backuping an instance
+
+There are two ways to backup a PostgreSQL Cluster with this plugin through the CloudNativePG operator :
+
+* One shot backup, equivalent to running it by hand but through a `Backup`
+  object definition ;
+* With `Scheduled Backup` object, equivalent to defining a crontab entry to run a
+  backup periodically.
+
+Whatever the kind of backup, users can list and see them with the
+appropriate `kubectl` command :
+
+```console
+kubectl get backups.postgresql.cnpg.io
+```
+
+## One shot backup
+
+Backup can be requested through a `Backup` object, using the default 
+CloudNativePG CRD `Backup` definition. The pgbackrest plugin can be specified 
+when declaring the `Backup` object. The `method` should be set to
+`plugin` and the `pluginConfiguration.name` field to
+`pgbackrest.dalibo.com`.
+
+Here is a full example of a backup definition using the pgBackRest
+plugin :
+
+```yaml title="backup.yaml"
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Backup
+metadata:
+  name: backup-example
+spec:
+  method: plugin
+  cluster:
+    name: cluster-demo
+  pluginConfiguration:
+    name: pgbackrest.dalibo.com
+```
+
+It's also possible to use the `cnpg` plugin for `kubectl` to perform 
+your backup :
+
+```console
+kubectl cnpg backup cluster-demo -m plugin --plugin-name pgbackrest.dalibo.com
+```
+
+When performing a backup, you can choose the repository to which to push
+it. To do this, you need to define the `selectedRepository` key using
+the number of the repository, according to its position in the list of
+configured repositories. For example, to use the first repository:
+
+```yaml title="backup.yaml"
+[...]
+  pluginConfiguration:
+    name: pgbackrest.dalibo.com
+    parameters:
+      selectedRepository: "1"
+```
+
+Or with the `cnpg` plugin:
+
+```console
+kubectl cnpg backup cluster-demo -m plugin --plugin-name pgbackrest.dalibo.com \
+  --plugin-parameters selectedRepository=1
+```
+
+## Scheduled backup
+
+A scheduled backup uses almost the same definition as a one-shot backup. Only the kind should be changed to `ScheduledBackup`. When using this object, the schedule field (with a `crontab`-like annotation) should
+also be defined under the specification (`spec`).
+
+Here is a full example of a scheduled backup definition using the
+pgbackrest plugin :
+
+```yaml title="scheduled-backup.yaml"
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: ScheduledBackup
+metadata:
+  name: backup-example
+spec:
+  schedule: "0 30 * * * *"
+  method: plugin
+  cluster:
+    name: cluster-demo
+  pluginConfiguration:
+    name: pgbackrest.dalibo.com
+```

docs/docs/contribute.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 6
+---
+
+# Contribute
+
+## Deploy CloudNativePG on kind
+
+To contribute and test the pgBackRest plugin, a dedicated Kubernetes
+cluster with the CloudNativePG operator is required. Contributors can use the `dev`
+version of the CloudNativePG operator and follow those steps to prepare the
+required environment.
+
+1. Clone the main CloudNativePG operator repository :
+```console
+git clone https://github.com/cloudnative-pg/cloudnative-pg
+```
+
+2. Move to the newly created directory : 
+
+```console
+cd cloudenative-pg
+```
+
+3. Install the required dependencies (please follow the instruction
+  within the README.md file, at least you will need
+  [**kind**](https://kind.sigs.k8s.io/)).
+
+4. Run a Kubernetes cluster with the development version of CloudNativePG :
+
+```console
+./hack/setup-cluster.sh create load deploy
+```
+
+:::info
+Contributors and users can also refer to the CloudNativePG documentation for more
+details on how it works and how to run the operator on
+[**kind**](https://kind.sigs.k8s.io/).
+:::
+
+## Deploy pgBackRest plugin
+
+The pgBackRest plugin can now be deployed on the newly created Kubernetes cluster.
+
+1. Clone the pgBackRest plugin repository :
+
+```console
+git clone https://github.com/dalibo/cnpg-plugin-pgbackrest
+```
+2. Move to the newly created directory : 
+
+```console
+cd cd cnpg-plugin-pgbackrest 
+```
+
+3. Build the container images used for the plugin (one for the controller and
+  another one for the sidecar container) :
+
+```console
+make build-images
+```
+
+4. The images must now be loaded into the registry dedicated the
+  development environment. This is feasible with the `kind load` command :
+
+```console
+kind load docker-image pgbackrest-{controller,sidecar}:latest --name <KUBERNETES-CLUSTER-NAME>
+```
+
+It's possible to retrieve the name of the Kubernetes cluster by running :
+```console
+kind get clusters
+```
+
+5. The plugin controller can now be deployed within the `cnpg-system`
+  namespace. For that the manifests on the `kubernetes` should be
+  applied:
+
+  ```console
+  kubectl apply -k ./kubernetes/dev
+  ```
+
+6. A `pgbackrest-controller` deployment must be present (e.g., in `cnpg-system` namespace). The plugin
+  controller should run on a dedicated `Pod` alongside the CloudNativePG operator `Pod`.
+
+7. Your are ready to contribute !
+
+## Executing E2E tests
+
+E2E Tests can be run automatically. To do that, the easiest approach is to
+use [**kind**](https://kind.sigs.k8s.io/) and the appropriate make
+target :
+
+```console
+make test-e2e
+```
+
+That command will:
+
+1. Create a dedicated Kubernetes cluster (managed by **kind** and named
+  `e2e-cnpg-pgbackrest`)
+2. Build the container images for the pgbackrest plugin
+3. Load them on the Kubernetes Cluster
+4 Run the tests defined on `test/e2e/e2e_test.go`, which also install
+  the dependencies and our plugin.
+
+To only run the tests (`test/e2e/e2e_test.go`), the `test-e2e-run-tests`
+target can be used :
+
+```console
+make test-e2e-run-tests
+```

docs/docs/howitworks.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 4
+---
+
+# How it works
+## How it works
+
+Here are some basic informations about how this plugin should work:
+
+- When installing the plugin, a new deployment is created to run a Pod
+  for the controller (`pgbackrest-controller`) of our plugin in the same
+  namespace as the CNPG operator.
+
+- The CNPG operator detects the plugin when a dedicated Kubernetes
+  Service (with some specific annotations) is created.
+
+- Our specialized controller exposes the supported capabilities (at
+  least those required to manage the
+  [lifecycle](https://pkg.go.dev/github.com/cloudnative-pg/cnpg-i@v0.1.0/pkg/lifecycle)
+  of our CNPG instances) to the CNPG operator.
+
+- When initializing a new Cluster configured with our plugin, the
+  pgBackRest controller will be called by the CloudNativePG operator.
+
+- The plugin controller modifies the resources (Deployment / Pods /
+  Jobs) requested by the CNPG operator (this is done before requesting
+  the Kubernetes API), and inject some configuration if needed.
+
+  For our pgbackrest plugin, the controller inject a sidecar container
+  for `pgBackRest` within the PostgreSQL Pods. This sidecar container
+  executes a manager dedicated to `pgBackRest` (which expose the
+  required capabilities archive the WAL and backup the PostgreSQL
+  instance).
+
+- Our newly created PostgreSQL instance will call the dedicated
+  `pgBackRest` manager (on the side container) when the archive command
+  is triggered.
+
+https://github.com/cloudnative-pg/cnpg-i/blob/main/docs/protocol.md#cnpgi-wal-v1-WALCapability-RPC