convert docs to Vitepress

.github/workflows/deploy_docs_2x.yml

@@ -20,4 +20,6 @@ jobs:
         uses: dokku/github-action@master
         with:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/queue-docs-2'
+          git_push_flags: '-f'
           ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
+          branch: '2.x'

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+    push:
+        branches:
+            - 2.x
+        paths:
+            - 'docs/**'
+            - '.github/**'
+    pull_request:
+        paths:
+            - 'docs/**'
+            - '.github/**'
+
+jobs:
+    validate:
+        uses: cakephp/.github/.github/workflows/docs-validation.yml@5.x
+        with:
+            docs-path: 'docs'
+            vitepress-path: 'docs/.vitepress'
+            enable-config-js-check: true
+            enable-json-lint: true
+            enable-toc-check: true
+            enable-spell-check: true
+            enable-markdown-lint: true
+            enable-link-check: true
+            tools-ref: '5.x'

Dockerfile

@@ -1,25 +1,36 @@
-# Basic docker based environment
-# Necessary to trick dokku into building the documentation
-# using dockerfile instead of herokuish
-FROM ubuntu:22.04
-
-# Add basic tools
-RUN apt-get update && \
-  apt-get install -y build-essential \
-    software-properties-common \
-    curl \
-    git \
-    libxml2 \
-    libffi-dev \
-    libssl-dev && \
-  LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php && \
-  apt-get update && \
-  apt-get install -y php8.1-cli php8.1-mbstring php8.1-xml php8.1-zip php8.1-intl php8.1-opcache php8.1-sqlite &&\
-  apt-get clean &&\
-  rm -rf /var/lib/apt/lists/*
-
-WORKDIR /code
-
-VOLUME ["/code"]
-
-CMD [ '/bin/bash' ]
+# ----------------------
+# 1. Build stage
+# ----------------------
+FROM node:24-alpine AS builder
+
+# Git is required because docs/package.json pulls a dependency from GitHub.
+RUN apk add --no-cache git openssh-client
+
+WORKDIR /app/docs
+
+# Copy dependency manifests first to preserve Docker layer caching.
+COPY docs/ ./
+RUN npm ci
+
+# Increase max-old-space-size to avoid memory issues during build
+#ENV NODE_OPTIONS="--max-old-space-size=8192"
+
+# Build the site.
+RUN npm run docs:build
+
+# ----------------------
+# 2. Runtime stage (angie)
+# ----------------------
+FROM docker.angie.software/angie:latest AS runner
+
+# Copy built files
+COPY --from=builder /app/docs/.vitepress/dist /usr/share/angie/html
+
+# Expose port
+EXPOSE 80
+
+# Health check (optional)
+HEALTHCHECK CMD wget --quiet --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start angie
+CMD ["angie", "-g", "daemon off;"]

docs/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+*/public/
+.vitepress/cache
+.vitepress/dist

docs/.vitepress/config.js

@@ -0,0 +1,53 @@
+import baseConfig from '@cakephp/docs-skeleton/config'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const tocEn = require('./toc_en.json')
+
+const versions = {
+  text: '2.x',
+  items: [
+    { text: '2.x (current)', link: 'https://book.cakephp.org/queue/2/', target: '_self' },
+    { text: '1.x', link: 'https://book.cakephp.org/queue/1/en/', target: '_self' },
+  ],
+}
+
+export default {
+  extends: baseConfig,
+  srcDir: '.',
+  title: 'Queue',
+  description: 'CakePHP Queue Documentation',
+  base: '/queue/2/',
+  rewrites: {
+    'en/:slug*': ':slug*',
+  },
+  sitemap: {
+    hostname: 'https://book.cakephp.org/queue/2/',
+  },
+  themeConfig: {
+    siteTitle: false,
+    pluginName: 'Queue',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/queue' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/cakephp/queue/edit/2.x/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    sidebar: tocEn,
+    nav: [
+      { text: 'CakePHP', link: 'https://cakephp.org' },
+      { text: 'API', link: 'https://api.cakephp.org/queue/' },
+      { ...versions },
+    ],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        sidebar: tocEn,
+      },
+    },
+  },
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1 @@
+export { default } from '@cakephp/docs-skeleton'

docs/.vitepress/toc_en.json

@@ -0,0 +1,29 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Installation and Configuration", "link": "/installation" },
+        { "text": "Defining and Queueing Jobs", "link": "/jobs" }
+      ]
+    },
+    {
+      "text": "Processing Work",
+      "collapsed": false,
+      "items": [
+        { "text": "Queueing Mail", "link": "/mail" },
+        { "text": "Custom Processors", "link": "/processors" },
+        { "text": "Running Workers", "link": "/workers" }
+      ]
+    },
+    {
+      "text": "Operations",
+      "collapsed": false,
+      "items": [
+        { "text": "Failed Jobs", "link": "/failed-jobs" },
+        { "text": "Worker Events", "link": "/events" }
+      ]
+    }
+  ]
+}

docs/en/events.md

@@ -0,0 +1,13 @@
+# Worker Events
+
+Workers dispatch events during normal message processing. If your queue config defines a `listener`, that class can subscribe to these events and react to worker activity.
+
+## Available Events
+
+- `Processor.message.exception`: dispatched when a message throws an exception. Arguments: `message`, `exception`.
+- `Processor.message.invalid`: dispatched when a message contains an invalid callable. Arguments: `message`.
+- `Processor.message.reject`: dispatched when a message finishes with `Processor::REJECT`. Arguments: `message`.
+- `Processor.message.success`: dispatched when a message finishes with `Processor::ACK`. Arguments: `message`.
+- `Processor.message.failure`: dispatched when a message finishes with `Processor::REQUEUE`. Arguments: `message`.
+- `Processor.message.seen`: dispatched when a message is first observed by the worker. Arguments: `message`.
+- `Processor.message.start`: dispatched immediately before processing begins. Arguments: `message`.

docs/en/failed-jobs.md

@@ -0,0 +1,48 @@
+# Failed Jobs
+
+By default, jobs that throw exceptions are requeued indefinitely. A job is treated as failed only when it returns `Processor::REQUEUE` or throws an exception and no retry attempts remain.
+
+Retry limits can come from:
+
+- The job class property `public static $maxAttempts`.
+- The worker command option `--max-attempts`.
+
+If `storeFailedJobs` is enabled, failed jobs are rejected, written to the `queue_failed_jobs` table, and can later be requeued manually. The original `config`, `queue`, and `priority` options are preserved.
+
+Your broker may also support dead-letter queues. Those are separate transport-level features. Queue's failed-job storage is transport-agnostic and only tracks jobs that exhaust Queue's retry handling.
+
+## Requeue Failed Jobs
+
+Push failed jobs back onto the queue:
+
+```bash
+bin/cake queue requeue
+```
+
+Filters:
+
+- Positional `ids` argument: comma-separated failed job IDs.
+- `--class`: filter by job class.
+- `--queue`: filter by queue name.
+- `--config`: filter by queue config.
+- `--force` or `-f`: skip the confirmation prompt.
+
+If no filters are provided, all stored failed jobs are requeued.
+
+## Purge Failed Jobs
+
+Delete failed jobs from the database:
+
+```bash
+bin/cake queue purge_failed
+```
+
+Filters:
+
+- Positional `ids` argument: comma-separated failed job IDs.
+- `--class`: filter by job class.
+- `--queue`: filter by queue name.
+- `--config`: filter by queue config.
+- `--force` or `-f`: skip the confirmation prompt.
+
+If no filters are provided, all stored failed jobs are deleted.

docs/en/index.md

@@ -0,0 +1,15 @@
+# Queue
+
+The Queue plugin provides an easy-to-use interface for the [php-enqueue](https://php-enqueue.github.io) project, which abstracts a wide range of queuing backends for CakePHP applications. Use it to move long-running work such as email delivery, notifications, or report generation out of the request cycle.
+
+Queue jobs are regular PHP classes. They can receive constructor dependencies from your application's container and are processed by the included `queue worker` command.
+
+## Documentation Map
+
+- [Installation and Configuration](/installation) covers plugin setup, transport configuration, and failed-job storage.
+- [Defining and Queueing Jobs](/jobs) explains job classes, message handling, unique jobs, and `QueueManager::push()`.
+- [Queueing Mail](/mail) shows how to queue mailer actions or send mail through the queue transport.
+- [Custom Processors](/processors) explains how to replace the default message processor.
+- [Running Workers](/workers) documents the worker command and its options.
+- [Failed Jobs](/failed-jobs) covers storing, requeueing, and purging failed jobs.
+- [Worker Events](/events) lists the events emitted while jobs are processed.