From 0e796289a0ef1f1eddc515476f9e03b87201dc97 Mon Sep 17 00:00:00 2001 From: d3xter666 Date: Mon, 23 Mar 2026 14:08:28 +0200 Subject: [PATCH 1/5] docs(documentation): Provide README.md --- internal/documentation/README.md | 60 ++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 internal/documentation/README.md diff --git a/internal/documentation/README.md b/internal/documentation/README.md new file mode 100644 index 00000000000..af01b65e7b3 --- /dev/null +++ b/internal/documentation/README.md @@ -0,0 +1,60 @@ +# UI5 CLI Documentation + +VitePress-based documentation site for the [UI5 CLI](https://github.com/UI5/cli) tooling. This internal package generates the static documentation published to GitHub Pages, including auto-generated API references (JSDoc), CLI command reference, and JSON Schema documentation. + +## Quick Start + +```bash +# Start the dev server (opens browser automatically) +npm start + +# Or without auto-opening the browser +npm run dev +``` + +The development server starts at `http://localhost:5173` with hot-reload for live editing. + +## Scripts + +### Development + +| Script | Purpose | +|--------|---------| +| `start` | Starts the VitePress dev server and opens the browser automatically. Primary entry point for local documentation development. | +| `dev` | Starts the VitePress dev server without opening the browser. Useful in container/remote environments or when the browser is already open. | +| `preview` | Serves the production build output (`dist/`) locally on port 8080 for verifying the built site before deployment. Requires `build:vitepress` to have been run first. | + +### Build & Deploy + +| Script | Purpose | +|--------|---------| +| `build:vitepress` | Builds the static site into the `dist/` directory. Requires `generate-cli-doc`, `schema-generate(-gh-pages)` and `jsdoc-generate(-gh-pages)` to be run first. | +| `build:assets` | Copies image assets from `docs/images/` to the build output directory. Must be run after `build:vitepress`. Accepts an optional destination path argument (defaults to `./dist`). | + +### Code Generation + +| Script | Purpose | +|--------|---------| +| `generate-cli-doc` | Executes `ui5 --help` (and subcommand help), parses the output, and renders `docs/pages/CLI.md` using a Handlebars template. The generated file is committed to the repository. | +| `schema-generate` | Bundles JSON Schema files from the local `@ui5/project` workspace package into `schema/ui5.yaml.json` and `schema/ui5-workspace.yaml.json`. | +| `schema-generate-gh-pages` | Same as `schema-generate` but reads schemas from downloaded packages in `tmp/packages/` (populated by `download-packages`) instead of the local workspace. Used for building documentation of published releases (v4). | +| `download-packages` | Downloads the latest published versions of all UI5 CLI packages (`@ui5/builder`, `@ui5/cli`, etc.) via `npm pack` and extracts them to `tmp/packages/`. This enables gh-pages builds to use published npm packages instead of local workspace code. | +| `jsdoc-generate` | Generates API documentation from local workspace package sources (`../../packages/*/lib/**/*.js`). Uses the workspace JSDoc config targeting the current development version (v5). | +| `jsdoc-generate-gh-pages` | Generates API documentation from downloaded packages in `tmp/packages/`. Uses the gh-pages JSDoc config targeting the published version (v4). Requires `download-packages` to run first. | +| `jsdoc` | Generates JSDoc API documentation from the local workspace and opens the result in the browser. Convenience wrapper for local development. | + + +## Dual-Version Documentation + +This package supports building documentation for two different versions: + +| Variant | JSDoc Config | Schema Mode | Sources | Target | +|---------|-------------|-------------|---------|--------| +| **Workspace (v5)** | `jsdoc-workspace.json` | `buildSchema.js` (default) | Local monorepo packages (`../../packages/`) | Current development version (v5) | +| **\*-gh-pages** | `jsdoc.json` | `buildSchema.js gh-pages` | Downloaded npm packages (`tmp/packages/`) | Published stable version (v4) | + +The **workspace** variants are used for local development and v5 documentation. The **\*-gh-pages** variants are used during deployment to generate documentation from published package versions (v4). + +## License + +Apache-2.0 — see [LICENSE.txt](../../LICENSE.txt). From bdf0ba1cdce8afe5786da86a0a25d71e4bdc86f7 Mon Sep 17 00:00:00 2001 From: Yavor Ivanov Date: Tue, 24 Mar 2026 09:08:52 +0200 Subject: [PATCH 2/5] docs: Update internal/documentation/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Günter Klatt --- internal/documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/documentation/README.md b/internal/documentation/README.md index af01b65e7b3..98cf68a6d3a 100644 --- a/internal/documentation/README.md +++ b/internal/documentation/README.md @@ -1,6 +1,6 @@ # UI5 CLI Documentation -VitePress-based documentation site for the [UI5 CLI](https://github.com/UI5/cli) tooling. This internal package generates the static documentation published to GitHub Pages, including auto-generated API references (JSDoc), CLI command reference, and JSON Schema documentation. +VitePress-based documentation site for the [UI5 CLI](https://github.com/UI5/cli) tooling. This internal package generates the static documentation published to GitHub Pages, including the auto-generated API reference (JSDoc), CLI command reference, and JSON Schema documentation. ## Quick Start From 8a0aaa9e75a32a5557a86f4c38559f435f054726 Mon Sep 17 00:00:00 2001 From: Yavor Ivanov Date: Tue, 24 Mar 2026 09:09:05 +0200 Subject: [PATCH 3/5] docs: Update internal/documentation/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Günter Klatt --- internal/documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/documentation/README.md b/internal/documentation/README.md index 98cf68a6d3a..6312403fc0b 100644 --- a/internal/documentation/README.md +++ b/internal/documentation/README.md @@ -20,7 +20,7 @@ The development server starts at `http://localhost:5173` with hot-reload for liv | Script | Purpose | |--------|---------| -| `start` | Starts the VitePress dev server and opens the browser automatically. Primary entry point for local documentation development. | +| `start` | Starts the VitePress dev server and opens the browser automatically. This is the primary entry point for local documentation development. | | `dev` | Starts the VitePress dev server without opening the browser. Useful in container/remote environments or when the browser is already open. | | `preview` | Serves the production build output (`dist/`) locally on port 8080 for verifying the built site before deployment. Requires `build:vitepress` to have been run first. | From 5069bd9060cabf0d42cd5d8b276df099cc4d1c33 Mon Sep 17 00:00:00 2001 From: Yavor Ivanov Date: Tue, 24 Mar 2026 09:09:12 +0200 Subject: [PATCH 4/5] docs: Update internal/documentation/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Günter Klatt --- internal/documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/documentation/README.md b/internal/documentation/README.md index 6312403fc0b..03515f0f68e 100644 --- a/internal/documentation/README.md +++ b/internal/documentation/README.md @@ -22,7 +22,7 @@ The development server starts at `http://localhost:5173` with hot-reload for liv |--------|---------| | `start` | Starts the VitePress dev server and opens the browser automatically. This is the primary entry point for local documentation development. | | `dev` | Starts the VitePress dev server without opening the browser. Useful in container/remote environments or when the browser is already open. | -| `preview` | Serves the production build output (`dist/`) locally on port 8080 for verifying the built site before deployment. Requires `build:vitepress` to have been run first. | +| `preview` | Serves the production build output (`dist/`) locally on port 8080 for verifying the built site before deployment. Requires `build:vitepress` to run first. | ### Build & Deploy From 50888ec6f259212238e9dba46ffe0e9170bc33b9 Mon Sep 17 00:00:00 2001 From: Yavor Ivanov Date: Tue, 24 Mar 2026 09:09:19 +0200 Subject: [PATCH 5/5] docs: Update internal/documentation/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Günter Klatt --- internal/documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/documentation/README.md b/internal/documentation/README.md index 03515f0f68e..1d6b40da1ec 100644 --- a/internal/documentation/README.md +++ b/internal/documentation/README.md @@ -28,7 +28,7 @@ The development server starts at `http://localhost:5173` with hot-reload for liv | Script | Purpose | |--------|---------| -| `build:vitepress` | Builds the static site into the `dist/` directory. Requires `generate-cli-doc`, `schema-generate(-gh-pages)` and `jsdoc-generate(-gh-pages)` to be run first. | +| `build:vitepress` | Builds the static site into the `dist/` directory. Requires `generate-cli-doc`, `schema-generate(-gh-pages)` and `jsdoc-generate(-gh-pages)` to run first. | | `build:assets` | Copies image assets from `docs/images/` to the build output directory. Must be run after `build:vitepress`. Accepts an optional destination path argument (defaults to `./dist`). | ### Code Generation