From 6cd63e1dcf13e2cebae3a0a0e359e2d3bccbea0d Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Fri, 6 Jan 2023 14:29:31 +0100 Subject: [PATCH 1/2] Fix building the documentation * Add `typedoc.json` instead of command-line flags, as the interface changed * Add plugin to document not exported objects (needed for the gettext module) * Add some module description for index and gettext Signed-off-by: Ferdinand Thiessen --- lib/gettext.ts | 32 +++++++++++++++++++++++++++++--- lib/index.ts | 15 +++++++++++++++ lib/translation.ts | 1 + package-lock.json | 17 +++++++++++++++++ package.json | 3 ++- typedoc.json | 10 ++++++++++ 6 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 typedoc.json diff --git a/lib/gettext.ts b/lib/gettext.ts index eadcb348..20db50f6 100644 --- a/lib/gettext.ts +++ b/lib/gettext.ts @@ -1,7 +1,27 @@ +/** + * This module provides functionality to translate applications independent from Nextcloud + * + * @packageDocumentation + * @module @nextcloud/l10n/gettext + * @example + * ```js +import { getGettextBuilder } from '@nextcloud/l10n/gettext' + +const gt = getGettextBuilder() + .detectLocale() // or use setLanguage() + .addTranslation(/* ... *\/) + .build() + +gt.gettext('some string to translate') +``` + */ import GetText from "node-gettext" import { getLanguage } from "." +/** + * @notExported + */ class GettextBuilder { private locale?: string @@ -13,6 +33,7 @@ class GettextBuilder { return this } + /** Try to detect locale from context with `en` as fallback value */ detectLocale(): GettextBuilder { return this.setLanguage(getLanguage().replace('-', '_')) } @@ -33,6 +54,9 @@ class GettextBuilder { } +/** + * @notExported + */ class GettextWrapper { private gt: GetText @@ -50,7 +74,7 @@ class GettextWrapper { this.gt.setLocale(locale) } - private subtitudePlaceholders(translated: string, vars: object): string { + private subtitudePlaceholders(translated: string, vars: Record): string { return translated.replace(/{([^{}]*)}/g, (a, b) => { const r = vars[b] if (typeof r === 'string' || typeof r === 'number') { @@ -61,14 +85,16 @@ class GettextWrapper { }) } - gettext(original: string, placeholders: object = {}): string { + /** Get translated string (singular form), optionally with placeholders */ + gettext(original: string, placeholders: Record = {}): string { return this.subtitudePlaceholders( this.gt.gettext(original), placeholders ) } - ngettext(singular: string, plural: string, count: number, placeholders: object = {}): string { + /** Get translated string with plural forms */ + ngettext(singular: string, plural: string, count: number, placeholders: Record = {}): string { return this.subtitudePlaceholders( this.gt.ngettext(singular, plural, count).replace(/%n/g, count.toString()), placeholders diff --git a/lib/index.ts b/lib/index.ts index b8f6bafe..47f95811 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -1,2 +1,17 @@ +/** + * This module provides all functions for the `OC.L10N` namespace + * + * @packageDocumentation + * @module @nextcloud/l10n + * @example + * ```js +import { translate as t, translatePlural as n } from '@nextcloud/l10n' + +console.log(t('my-app', 'Hello {name}', { name: 'J. Doe' })); +const count = 2; +console.warn(n('my-app', 'Got an error', 'Got multiple errors', 2)); +``` + */ + export * from './translation' export * from './date' diff --git a/lib/translation.ts b/lib/translation.ts index f8100367..72e7feb9 100644 --- a/lib/translation.ts +++ b/lib/translation.ts @@ -10,6 +10,7 @@ import { generateFilePath } from '@nextcloud/router' import DOMPurify from 'dompurify' import escapeHTML from 'escape-html' +/** @notExported */ interface TranslationOptions { /** enable/disable auto escape of placeholders (by default enabled) */ escape?: boolean diff --git a/package-lock.json b/package-lock.json index 17d985d0..9d3bc41a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,7 @@ "@nextcloud/browserslist-config": "^2.3.0", "@nextcloud/typings": "^1.0.0", "@types/node-gettext": "^3.0", + "@zamiell/typedoc-plugin-not-exported": "^0.2.0", "check-es-compat": "^2.2.0", "gettext-parser": "^6.0.0", "jest": "^29.3.1", @@ -1359,6 +1360,15 @@ "integrity": "sha512-iO9ZQHkZxHn4mSakYV0vFHAVDyEOIJQrV2uZ06HxEPcx+mt8swXoZHIbaaJ2crJYFfErySgktuTZ3BeLz+XmFA==", "dev": true }, + "node_modules/@zamiell/typedoc-plugin-not-exported": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@zamiell/typedoc-plugin-not-exported/-/typedoc-plugin-not-exported-0.2.0.tgz", + "integrity": "sha512-R0EOvUfSc7APvBL5ZRkW3J1g/McWnMrVeVaIwrCmz9IiWjQ8LuLumRQxRICuiCz9FEwa3Giz/7SJXbbLf8bQ3A==", + "dev": true, + "peerDependencies": { + "typedoc": ">=0.22.17" + } + }, "node_modules/abab": { "version": "2.0.6", "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz", @@ -6446,6 +6456,13 @@ "integrity": "sha512-iO9ZQHkZxHn4mSakYV0vFHAVDyEOIJQrV2uZ06HxEPcx+mt8swXoZHIbaaJ2crJYFfErySgktuTZ3BeLz+XmFA==", "dev": true }, + "@zamiell/typedoc-plugin-not-exported": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@zamiell/typedoc-plugin-not-exported/-/typedoc-plugin-not-exported-0.2.0.tgz", + "integrity": "sha512-R0EOvUfSc7APvBL5ZRkW3J1g/McWnMrVeVaIwrCmz9IiWjQ8LuLumRQxRICuiCz9FEwa3Giz/7SJXbbLf8bQ3A==", + "dev": true, + "requires": {} + }, "abab": { "version": "2.0.6", "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz", diff --git a/package.json b/package.json index 4e44d528..9089c869 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ }, "scripts": { "build": "tsc && tsc --project tsconfig.cjs.json", - "build:doc": "typedoc --excludeNotExported --mode file --out dist/doc lib && touch dist/doc/.nojekyll", + "build:doc": "typedoc && touch dist/doc/.nojekyll", "check-types": "tsc --noEmit", "check-es-compat": "npm run build && check-es-compat dist/*.js", "dev": "tsc --watch", @@ -43,6 +43,7 @@ "@nextcloud/browserslist-config": "^2.3.0", "@nextcloud/typings": "^1.0.0", "@types/node-gettext": "^3.0", + "@zamiell/typedoc-plugin-not-exported": "^0.2.0", "check-es-compat": "^2.2.0", "gettext-parser": "^6.0.0", "jest": "^29.3.1", diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000..765ffbbd --- /dev/null +++ b/typedoc.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["./lib/index.ts", "./lib/gettext.ts"], + "out": "dist/doc", + "excludePrivate": true, + "navigationLinks": { + "GitHub": "https://github.com/nextcloud/nextcloud-l10n/", + "Nextcloud": "https://docs.nextcloud.com/server/stable/developer_manual/basics/front-end/l10n.html" + } +} From 2b7c2180832520b9f31b869b494107c0a490aea6 Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Fri, 6 Jan 2023 14:35:29 +0100 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=91=B7=20Added=20CI=20for=20deploying?= =?UTF-8?q?=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Ferdinand Thiessen --- .github/workflows/documentation.yml | 32 +++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..44f20933 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,32 @@ +name: Deploy documentation +on: + push: + branches: + - master + +permissions: + contents: write + +jobs: + build-and-deploy: + concurrency: ci-${{ github.ref }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Set up node + uses: actions/setup-node@v3 + with: + node-version-file: 'package.json' + + - name: Install dependencies & build + run: | + npm ci + npm run build:doc + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: dist/doc + branch: gh-pages