diff --git a/.github/workflows/deploy-docs-next.yaml b/.github/workflows/deploy-docs-next.yaml new file mode 100644 index 0000000000..a5a742a041 --- /dev/null +++ b/.github/workflows/deploy-docs-next.yaml @@ -0,0 +1,94 @@ +# Sample workflow for building and deploying a VitePress site to GitHub Pages +# +name: Deploy VitePress site to Pages (next) + +on: + # Runs on pushes targeting the `main` branch. Change this to `master` if you're + # using the `master` branch as the default branch. + push: + branches: [main] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: write + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + # Build job + deploy-docs: + runs-on: ubuntu-latest + env: + DOC_VERSION: v5 # The directory in gh-pages where the documentation would be deployed + DOC_ALIAS: next # Change this to update the alias route. Note: Check the old alias when changing this! + GIT_COMMITTER_NAME: "OpenUI5 Bot" + GIT_COMMITTER_EMAIL: "openui5@sap.com" + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Install dependencies + run: npm ci + - name: Install documentation dependencies + run: cd packages/documentation && npm ci + - name: Fetch gh-pages branch + run: git fetch origin gh-pages --depth=1 + - name: Set /site ownership to current user + run: | + mkdir site + sudo chown -R $(id -u):$(id -g) ./site + - name: generate CLI doc + run: npm run generate-cli-doc + - name: Build jsdoc + run: npm run jsdoc-generate + - name: Build vitepress build + run: npm run docs:build + - name: Build Schema + run: | + npm run schema-generate + npm run schema-workspace-generate + - name: Checkout gh-pages + uses: actions/checkout@v4 + with: + ref: gh-pages + path: gh-pages + - name: Copy the additional resources to gh-pages + run: | + rm -rf ./gh-pages/schema + cp -R ./site/schema ./gh-pages/ + rm -rf ./gh-pages/${DOC_VERSION}/ + cp -R ./packages/documentation/dist ./gh-pages/${DOC_VERSION}/ + cp ./scripts/resources/custom404.html ./gh-pages/404.html + - name: Create or update alias route + run: | + cd ./gh-pages + # Remove existing alias if it exists (file or symlink) + rm -rf "${DOC_ALIAS}" + # Create symlink from alias to version directory + ln -s "${DOC_VERSION}" "${DOC_ALIAS}" + - name: Publish Docs + run: | + cd ./gh-pages + git config --local user.email $GIT_COMMITTER_EMAIL + git config --local user.name $GIT_COMMITTER_NAME + git add . + git commit -m "Updating supplemental resources for ${DOC_VERSION} documentation deployment" + git push diff --git a/.gitignore b/.gitignore index 7a19eaec87..ff22bb45c6 100644 --- a/.gitignore +++ b/.gitignore @@ -59,11 +59,11 @@ deploy_key jsdocs/ site/ -# Needed for packages/server -!packages/**/test/fixtures/**/node_modules +# Needed for packages/server # Custom files +!packages/**/test/fixtures/**/node_modules -# Documentation +# Documentation packages/documentation/docs/pages/CLI.md packages/documentation/.vitepress/dist packages/documentation/.vitepress/cache -packages/documentation/dist +packages/documentation/dist \ No newline at end of file diff --git a/README.md b/README.md index a167ccfef1..c2fc494aff 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,10 @@ ## Resources -- [Documentation](https://ui5.github.io/cli/stable/) -- [API Reference](https://ui5.github.io/cli/stable/api/) -- [CLI Documentation](https://ui5.github.io/cli/stable/pages/CLI/) -- [Project Configuration](https://ui5.github.io/cli/stable/pages/Configuration/) +- [Documentation](https://ui5.github.io/cli/v4/) +- [API Reference](https://ui5.github.io/cli/v4/api/) +- [CLI Documentation](https://ui5.github.io/cli/v4/pages/CLI/) +- [Project Configuration](https://ui5.github.io/cli/v4/pages/Configuration/) - 🎬 [UI5con@SAP 2020 Talk](https://www.youtube.com/watch?v=8IHoVJLKN34) - 🎬 [UI5con@SAP 2018 Talk](https://www.youtube.com/watch?v=iQ07oe26y_k) - [Contribution Guidelines](https://github.com/UI5/cli/blob/main/CONTRIBUTING.md) @@ -48,3 +48,6 @@ Please check our [Contribution Guidelines](https://github.com/UI5/cli/blob/main/ ## Support Please follow our [Contribution Guidelines](https://github.com/UI5/cli/blob/main/CONTRIBUTING.md#report-an-issue) on how to report an issue. Or chat with us in the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com). For public Q&A, use the [`ui5-tooling` tag on Stack Overflow](https://stackoverflow.com/questions/tagged/ui5-tooling). + +## Kudos +Thanks goes out for the amazing [UI5 VitePress|https://github.com/hschaefer123/ui5-vitepress] project offered by [Holger Schäfer|https://github.com/hschaefer123] on which the UI5 CLI documentation is based. \ No newline at end of file diff --git a/REUSE.toml b/REUSE.toml index d52635f380..07f4ef69dd 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -26,4 +26,10 @@ SPDX-License-Identifier = "Apache-2.0" path = "packages/builder/lib/processors/jsdoc/lib/**" precedence = "aggregate" SPDX-FileCopyrightText = "2025 SAP SE or an SAP affiliate company and OpenUI5 contributors" -SPDX-License-Identifier = "Apache-2.0" \ No newline at end of file +SPDX-License-Identifier = "Apache-2.0" + +[[annotations]] +path = "packages/documentation/.vitepress/**" +precedence = "aggregate" +SPDX-FileCopyrightText = ["2019-present, Konrad Kost, Holger Schäfer, Yuxi (Evan) and VitePress contributors"] +SPDX-License-Identifier = "MIT" \ No newline at end of file diff --git a/jsdoc-workspace.json b/jsdoc-workspace.json index 603e68cac7..66fe780522 100644 --- a/jsdoc-workspace.json +++ b/jsdoc-workspace.json @@ -3,9 +3,9 @@ "allowUnknownTags": false }, "source": { - "include": ["docs/indexJsdoc.md"], - "exclude": ["../ui5-builder/lib/lbt/utils/JSTokenizer.js"], - "includePattern": "ui5-[^\/]+\/(lib/.+|index)\\.js$" + "include": ["packages/documentation/docs/indexJsdoc.md"], + "exclude": ["packages/builder/lib/lbt/utils/JSTokenizer.js"], + "includePattern": "packages/[^\/]+\/(lib/.+|index)\\.js$" }, "plugins": [ "jsdoc-plugin.cjs" diff --git a/jsdoc.json b/jsdoc.json deleted file mode 100644 index 124be7ba83..0000000000 --- a/jsdoc.json +++ /dev/null @@ -1,71 +0,0 @@ -{ - "tags": { - "allowUnknownTags": false - }, - "source": { - "include": ["packages/documentation/docs/indexJsdoc.md"], - "exclude": [ - "node_modules/@ui5/builder/lib/lbt/utils/JSTokenizer.js", - "node_modules/@ui5/builder/lib/processors/jsdoc/lib/ui5/plugin.js", - "node_modules/@ui5/builder/lib/processors/jsdoc/lib/ui5/template/publish.js", - "node_modules/@ui5/builder/lib/processors/jsdoc/lib/ui5/template/utils/versionUtil.js" - ], - "includePattern": "node_modules/@ui5/[^\/]*/(lib/.+|index)\\.js$", - "excludePattern": "node_modules/@ui5/.*/node_modules/@ui5" - }, - "plugins": [ - "./jsdoc-plugin.cjs" - ], - "opts": { - "encoding": "utf8", - "destination": "site/api/", - "recurse": true, - "verbose": true, - "access": "public" - }, - "templates": { - "cleverLinks": false, - "monospaceLinks": false, - "default": { - "useLongnameInNav": true, - "layoutFile": "lib/jsdoc/plugin/template/layout.tmpl", - "staticFiles": { - "include": ["lib/jsdoc/plugin/template/custom.css"] - } - } - }, - "openGraph": { - "title": "UI5 CLI - API Reference", - "type": "website", - "image": "https://ui5.github.io/cli/v4/images/UI5_logo_wide.png", - "site_name": "UI5 CLI - API Reference", - "url": "https://ui5.github.io/cli/v4/" - }, - "docdash": { - "sectionOrder": [ - "Modules", - "Namespaces", - "Classes", - "Externals", - "Events", - "Mixins", - "Tutorials", - "Interfaces" - ], - "meta": { - "title": "UI5 CLI - API Reference", - "description": "UI5 CLI - API Reference", - "keyword": "openui5 sapui5 ui5 build development tool api reference" - }, - "search": true, - "wrap": true, - "menu": { - "GitHub": { - "href": "https://github.com/UI5/cli", - "target": "_blank", - "class": "menu-item", - "id": "github_link" - } - } - } -} diff --git a/package.json b/package.json index c770b1f713..f81db442f6 100644 --- a/package.json +++ b/package.json @@ -27,11 +27,10 @@ "lint": "eslint ./ && npm run lint --workspaces", "coverage": "npm run coverage --workspaces", "jsdoc": "npm run jsdoc-generate && open-cli site/api/index.html", - "jsdoc-generate": "node ./scripts/isWorkspace.js && npm run jsdoc-generate-workspace || npm run jsdoc-generate-local", - "jsdoc-generate-local": "jsdoc -c ./jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)", - "jsdoc-generate-workspace": "jsdoc -c ./jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ../ || (echo 'Error during JSDoc generation! Check log.' && exit 1)", - "docs": "bash ./scripts/serveDocs.sh", - "docs-generate": "bash ./scripts/buildDocs.sh && open-cli http://localhost:8000 && ws --compress -d site", + "jsdoc-generate": "jsdoc -c ./jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)", + "docs:dev": "npm --prefix packages/documentation run dev", + "docs:build": "npm --prefix packages/documentation run build", + "docs:preview": "npm --prefix packages/documentation run preview", "schema-generate": "node ./scripts/buildSchema.js ui5", "schema-workspace-generate": "node ./scripts/buildSchema.js ui5-workspace", "generate-cli-doc": "node ./scripts/generateCliDoc.js", diff --git a/packages/documentation/.vitepress/config.ts b/packages/documentation/.vitepress/config.ts index 765a6cb178..7600cb3efe 100644 --- a/packages/documentation/.vitepress/config.ts +++ b/packages/documentation/.vitepress/config.ts @@ -7,8 +7,8 @@ import MarkdownItImplicitFigures from "markdown-it-implicit-figures"; import MarkdownItPlantuml from "markdown-it-plantuml"; export default defineConfig({ - - base: "/ui5-cli/stable/", // use this for github pages deployment or remove for CF + + base: "/ui5-cli/v5/", // use this for github pages deployment or remove for CF srcDir: "docs", outDir: "dist", lang: "en-US", @@ -129,8 +129,13 @@ function nav() { return [ { - text: 'V4', + text: 'V5', items: [ + { + text: 'V4', + link: '../v4/', + target: "_self" + }, { text: 'V3', link: '../v3/', @@ -142,7 +147,7 @@ function nav() { target: "_self" } ] - }, + } ]; } diff --git a/scripts/isWorkspace.js b/scripts/isWorkspace.js deleted file mode 100644 index ec02240b99..0000000000 --- a/scripts/isWorkspace.js +++ /dev/null @@ -1,9 +0,0 @@ -import path from "node:path"; -import {fileURLToPath} from "node:url"; - -const cliPath = path.relative(import.meta.dirname, fileURLToPath(import.meta.resolve("@ui5/cli/package.json"))); - -// no workspace detected -if (!cliPath.startsWith(path.join("..", ".."))) { - process.exit(1); -}