diff --git a/internal/documentation/.vitepress/config.ts b/internal/documentation/.vitepress/config.ts index 4af2da04ce8..bf7e7e4cd22 100644 --- a/internal/documentation/.vitepress/config.ts +++ b/internal/documentation/.vitepress/config.ts @@ -285,7 +285,7 @@ function guide() { (() => { // This function builds the tree for the api docs const tree = { - text: "API", + text: "📚 API", collapsed: false, items: [{ text: "@ui5", diff --git a/internal/documentation/README.md b/internal/documentation/README.md index 1d6b40da1ec..f9db20264cd 100644 --- a/internal/documentation/README.md +++ b/internal/documentation/README.md @@ -41,7 +41,6 @@ The development server starts at `http://localhost:5173` with hot-reload for liv | `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 diff --git a/internal/documentation/docs/index.md b/internal/documentation/docs/index.md index 12497504b55..c87ec024b8b 100644 --- a/internal/documentation/docs/index.md +++ b/internal/documentation/docs/index.md @@ -107,7 +107,7 @@ info ProjectBuilder Executing cleanup tasks... Most UI5 CLI modules provide JavaScript APIs for direct consumption in other Node.js projects. This allows you to rely on UI5 CLI for UI5-specific build functionality and project handling, while creating your own tools to perfectly match the needs of your project. -All available APIs are documented in the [UI5 CLI API Reference](https://ui5.github.io/cli/v5/api/index.html). +All available APIs are documented directly within this documentation. Use the sidebar menu and navigate to **📚 API** to browse the API reference for each package. ::: code-group ```js [ESM] diff --git a/internal/documentation/docs/pages/Builder.md b/internal/documentation/docs/pages/Builder.md index d36be96ec98..ef73c37c1b4 100644 --- a/internal/documentation/docs/pages/Builder.md +++ b/internal/documentation/docs/pages/Builder.md @@ -10,9 +10,9 @@ Based on a project's type, the UI5 Builder defines a series of build steps to ex For every type there is a set of default tasks. You can disable single tasks using the `--exclude-task` [CLI parameter](./CLI.md#ui5-build), and you can include tasks using the `--include-task` parameter. -
- -
+::: tip +Browse the API reference for each Builder API by navigating in the sidebar menu to **📚 API -> @ui5/builder**. +::: ## Tasks Tasks are specific build steps to be executed during build phase. @@ -23,31 +23,31 @@ A project can add custom tasks to the build by using the [Custom Tasks Extensibi ### Standard Tasks -All available standard tasks are documented [in the API reference](https://ui5.github.io/cli/v5/api/index.html). Search for `@ui5/builder/tasks/` to filter the API reference for all available tasks. The list below offers the actual order of their execution: +All available standard tasks are documented under **📚 API -> @ui5/builder -> tasks**. Use the sidebar menu to access the respective pages. The list below offers the actual order of their execution: | Task | Type `application` | Type `component` | Type `library` | Type `theme-library` | |--------------------------------|:-----------------------:|:-----------------------:|:-----------------------:|:-----------------------:| -| escapeNonAsciiCharacters | enabled | enabled | enabled | | -| replaceCopyright | enabled | enabled | enabled | enabled | -| replaceVersion | enabled | enabled | enabled | enabled | -| replaceBuildtime | | | enabled | | -| generateJsdoc | | | *disabled* 1 | | -| executeJsdocSdkTransformation | | | *disabled* 1 | | -| minify | enabled | enabled | enabled | | -| generateFlexChangesBundle | enabled | enabled | enabled | | -| generateLibraryManifest | | | enabled | | -| enhanceManifest | enabled | enabled | enabled | | -| generateComponentPreload | enabled | enabled | *disabled* 2 | | -| generateLibraryPreload | | | enabled | | -| generateStandaloneAppBundle | *disabled* 3 | | | | -| transformBootstrapHtml | *disabled* 3 | | | | -| generateBundle | *disabled* 4 | *disabled* 4 | *disabled* 4 | | -| buildThemes | | | enabled | enabled | -| generateThemeDesignerResources | | | *disabled* 5 | *disabled* 5 | -| generateVersionInfo | *disabled* 1 | | | | -| generateCachebusterInfo | *disabled* | *disabled* | | | -| generateApiIndex | *disabled* 1 | | | | -| generateResourcesJson | *disabled* | *disabled* | *disabled* | *disabled* | +| [escapeNonAsciiCharacters](../api/module-@ui5_builder_tasks_escapeNonAsciiCharacters) | enabled | enabled | enabled | | +| [replaceCopyright](../api/module-@ui5_builder_tasks_replaceCopyright) | enabled | enabled | enabled | enabled | +| [replaceVersion](../api/module-@ui5_builder_tasks_replaceVersion) | enabled | enabled | enabled | enabled | +| [replaceBuildtime](../api/module-@ui5_builder_tasks_replaceBuildtime) | | | enabled | | +| [generateJsdoc](../api/module-@ui5_builder_tasks_jsdoc_generateJsdoc) | | | *disabled* 1 | | +| [executeJsdocSdkTransformation](../api/module-@ui5_builder_tasks_jsdoc_executeJsdocSdkTransformation) | | | *disabled* 1 | | +| [minify](../api/module-@ui5_builder_tasks_minify) | enabled | enabled | enabled | | +| [generateFlexChangesBundle](../api/module-@ui5_builder_tasks_bundlers_generateFlexChangesBundle) | enabled | enabled | enabled | | +| [generateLibraryManifest](../api/module-@ui5_builder_tasks_generateLibraryManifest) | | | enabled | | +| [enhanceManifest](../api/module-@ui5_builder_tasks_enhanceManifest) | enabled | enabled | enabled | | +| [generateComponentPreload](../api/module-@ui5_builder_tasks_bundlers_generateComponentPreload) | enabled | enabled | *disabled* 2 | | +| [generateLibraryPreload](../api/module-@ui5_builder_tasks_bundlers_generateLibraryPreload) | | | enabled | | +| [generateStandaloneAppBundle](../api/module-@ui5_builder_tasks_bundlers_generateStandaloneAppBundle) | *disabled* 3 | | | | +| transformBootstrapHtml | *disabled* 3 | | | | +| [generateBundle](../api/module-@ui5_builder_tasks_bundlers_generateBundle) | *disabled* 4 | *disabled* 4 | *disabled* 4 | | +| [buildThemes](../api/module-@ui5_builder_tasks_buildThemes) | | | enabled | enabled | +| [generateThemeDesignerResources](../api/module-@ui5_builder_tasks_generateThemeDesignerResources) | | | *disabled* 5 | *disabled* 5 | +| [generateVersionInfo](../api/module-@ui5_builder_tasks_generateVersionInfo) | enabled | *disabled* | *disabled* | *disabled* | +| [generateCachebusterInfo](../api/module-@ui5_builder_tasks_generateCachebusterInfo) | *disabled* | *disabled* | | | +| [generateApiIndex](../api/module-@ui5_builder_tasks_jsdoc_generateApiIndex) | *disabled* 1 | | | | +| [generateResourcesJson](../api/module-@ui5_builder_tasks_generateResourcesJson) | *disabled* | *disabled* | *disabled* | *disabled* | *Disabled tasks can be activated by certain build modes, the project configuration, or by using the `--include-task` [CLI parameter](./CLI.md#ui5-build). See footnotes where given* @@ -157,7 +157,7 @@ Processors work with provided resources. They contain the actual build step logi Processors can be implemented generically. The string replacer is an example for that. Since string replacement is a common build step, it can be useful in different contexts, e.g. code, version, date, and copyright replacement. A concrete replacement operation could be achieved by passing a custom configuration to the processor. This way, multiple tasks can make use of the same processor to achieve their build step. -To get a list of all available processors, please visit [the API reference](https://ui5.github.io/cli/v5/api/index.html) and search for `@ui5/builder/processors/`. +To get a list of all available processors, use the sidebar menu and navigate to **📚 API -> @ui5/builder -> processors**. ## Legacy Bundle Tooling (lbt) JavaScript port of the "legacy" Maven/Java based bundle tooling. diff --git a/internal/documentation/docs/pages/Configuration.md b/internal/documentation/docs/pages/Configuration.md index 5e993a7c811..bb621b77e69 100644 --- a/internal/documentation/docs/pages/Configuration.md +++ b/internal/documentation/docs/pages/Configuration.md @@ -749,7 +749,7 @@ A list of bundle definitions. A `bundleDefinition` contains of the following opt - `name`: The module bundle name - `defaultFileTypes`: List of default file types which should be included in the bundle. Defaults to: `.js`, `.control.xml`, `.fragment.html`, `.fragment.json`, `.fragment.xml`, `.view.html`, `.view.json` and `.view.xml` -- `sections`: A list of module bundle definition sections. Each section specifies an embedding technology (see [API-Reference](https://ui5.github.io/cli/v5/api/module-@ui5_builder_processors_bundlers_moduleBundler.html#~ModuleBundleDefinition)) and lists the resources that should be in- or excluded from the section. +- `sections`: A list of module bundle definition sections. Each section specifies an embedding technology (see [📚 API-Reference](../api/module-@ui5_builder_processors_bundlers_moduleBundler.html#~ModuleBundleDefinition)) and lists the resources that should be in- or excluded from the section. - `mode`: The embedding technology (e.g. provided, raw, preload, bundleInfo, depCache, require) - `filters`: List of modules declared as glob patterns (resource name patterns) that are in- or excluded. Similarly to the use of a single `*` or double `**` asterisk, a pattern ending with a slash `/` denotes an arbitrary number of characters or folder names. Excludes have to be marked with a leading exclamation mark `!`. The order of filters is relevant; a later inclusion overrides an earlier exclusion, and vice versa. - `resolve`: Setting resolve to `true` will also include all (transitive) dependencies of the files diff --git a/internal/documentation/docs/pages/FileSystem.md b/internal/documentation/docs/pages/FileSystem.md index 371425e3a12..274d923643c 100644 --- a/internal/documentation/docs/pages/FileSystem.md +++ b/internal/documentation/docs/pages/FileSystem.md @@ -6,9 +6,9 @@ The [UI5 FS](https://github.com/SAP/ui5-fs) provides a UI5-specific file system import VPButton from "vitepress/dist/client/theme-default/components/VPButton.vue" -
- -
+::: tip +Browse the API reference for each FS API by navigating in the sidebar menu to **📚 API -> @ui5/fs**. +::: ## Overview @@ -16,7 +16,7 @@ The virtual file system "UI5 FS" offers an abstraction layer from the physical f ### Resource -A [Resource](https://ui5.github.io/cli/v5/api/@ui5_fs_Resource.html) basically represents a file. Besides providing access to the file content, it also carries metadata like the **virtual path** of the Resource. +A [Resource](../api/@ui5_fs_Resource.html) basically represents a file. Besides providing access to the file content, it also carries metadata like the **virtual path** of the Resource. Resources are typically created and stored in [Adapters](#adapters). Once read from a physical file system, they are typically kept in memory for further processing in other modules. @@ -26,9 +26,9 @@ This ensures a high build performance, as physical read and write access for a h Adapters abstract access to different resource locations. -The [Memory Adapter](https://ui5.github.io/cli/v5/api/@ui5_fs_adapters_Memory.html) represents a virtual file system which maintains respective [Resources](#resource) inside a virtual data structure. +The [Memory Adapter](../api/@ui5_fs_adapters_Memory.html) represents a virtual file system which maintains respective [Resources](#resource) inside a virtual data structure. -The [File System Adapter](https://ui5.github.io/cli/v5/api/@ui5_fs_adapters_FileSystem.html), on the other hand, has direct access to the physical file system. It maps a "virtual base path" to a given physical path. +The [File System Adapter](../api/@ui5_fs_adapters_FileSystem.html), on the other hand, has direct access to the physical file system. It maps a "virtual base path" to a given physical path. Both adapters provide APIs to retrieve and persist [Resources](#resource), namely @@ -43,10 +43,10 @@ Reader collections allow grouped access to multiple adapters, which might even b They implement the same API for **retrieving** resources as adapters (`byPath` and `byGlob`). Multiple flavors exist: -* [ReaderCollection](https://ui5.github.io/cli/v5/api/@ui5_fs_ReaderCollection.html): The most basic collection. Allows parallel read access to multiple readers (i.e. adapters or collections) -* [ReaderCollectionPrioritized](https://ui5.github.io/cli/v5/api/@ui5_fs_ReaderCollectionPrioritized.html): Contains a list of readers which are searched in-order. This allows one reader to "overlay" resources of another -* [DuplexCollection](https://ui5.github.io/cli/v5/api/@ui5_fs_DuplexCollection.html): Contains a single reader and a single "writer". It therefore also implements the Adapter API for **persisting** resources (`write()`). When retrieving resources, the writer is prioritized over the reader -* [WriterCollection](https://ui5.github.io/cli/v5/api/@ui5_fs_WriterCollection.html): Contains a set of writers and a mapping for each of them. When writing a resource, the writer is chosen based on the resource's virtual path. +* [ReaderCollection](../api/@ui5_fs_ReaderCollection.html): The most basic collection. Allows parallel read access to multiple readers (i.e. adapters or collections) +* [ReaderCollectionPrioritized](../api/@ui5_fs_ReaderCollectionPrioritized.html): Contains a list of readers which are searched in-order. This allows one reader to "overlay" resources of another +* [DuplexCollection](../api/@ui5_fs_DuplexCollection.html): Contains a single reader and a single "writer". It therefore also implements the Adapter API for **persisting** resources (`write()`). When retrieving resources, the writer is prioritized over the reader +* [WriterCollection](../api/@ui5_fs_WriterCollection.html): Contains a set of writers and a mapping for each of them. When writing a resource, the writer is chosen based on the resource's virtual path.