docs: autogenerate API reference with Typedoc (#127)

sumup-oss · Oct 17, 2022 · d856d84 · d856d84
1 parent dafc682
commit d856d84
Show file tree

Hide file tree

Showing 8 changed files with 312 additions and 307 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,29 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Use Node.js v16.13
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16.13
+          cache: 'yarn'
+      - name: Install dependencies
+        run: yarn --pure-lockfile --prefer-offline
+      - name: Generate documentation
+        run: yarn docs
+      - name: Upload documentation to GitHub Wiki
+        uses: SwiftDocOrg/github-wiki-publish-action@v1
+        with:
+          path: 'docs'
+        env:
+          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_ACTIONS_PAT }}
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 # Project
 
 dist
+docs
 junit.xml
 __coverage__
 __reports__

diff --git a/README.md b/README.md
@@ -13,10 +13,7 @@ Format 🔢 numbers and 💱currency values for any locale with the [ECMAScript
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Format as string](#format-as-string)
-  - [Format as parts](#format-as-parts)
-  - [Resolve format](#resolve-format)
-  - [Constants](#constants)
+- [API reference](https://github.com/sumup-oss/intl-js/wiki/Exports)
 - [Code of Conduct](#code-of-conduct)
 - [About SumUp](#about-sumup)
 
@@ -42,309 +39,25 @@ $ npm install @sumup/intl
 
 All functions exported by `@sumup/intl` share a similar interface such as the common [`locales`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument), [`options`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#options_argument), and [`currency`](https://en.wikipedia.org/wiki/ISO_4217) arguments. These are passed on almost unchanged to the [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) constructor and thus support the same values. If the `locales` argument is not provided or is undefined, the runtime's default locale is used. Please refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) for more details.
 
-### Format as string
+## API reference
 
-#### `formatNumber`
+### Number Functions
 
-Formats a number according to the locale with support for various [styles, units](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_style_and_unit), and [notations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_notation).
+- [formatNumber](https://github.com/sumup-oss/intl-js/wiki/Exports#formatnumber)
+- [formatNumberToParts](https://github.com/sumup-oss/intl-js/wiki/Exports#formatnumbertoparts)
+- [resolveNumberFormat](https://github.com/sumup-oss/intl-js/wiki/Exports#resolvenumberformat)
 
-**Arguments**
+### Currency Functions
 
-| Name     | Type                     | Examples                                                |
-| -------- | ------------------------ | ------------------------------------------------------- |
-| value    | number                   | `12345.67`, `-0.89`                                     |
-| locales? | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| options? | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
+- [formatCurrency](https://github.com/sumup-oss/intl-js/wiki/Exports#formatcurrency)
+- [formatCurrencyToParts](https://github.com/sumup-oss/intl-js/wiki/Exports#formatcurrencytoparts)
+- [resolveCurrencyFormat](https://github.com/sumup-oss/intl-js/wiki/Exports#resolvecurrencyformat)
 
-**Examples**
+### Variables
 
-```ts
-import { formatNumber } from '@sumup/intl';
-
-formatNumber(12345.67, 'de-DE'); // '12.345,67'
-formatNumber(-0.89, ['ban', 'id']); // '-0,89'
-formatNumber(16, 'en-GB', {
-  style: 'unit',
-  unit: 'liter',
-  unitDisplay: 'long',
-}); // 16 litres
-```
-
-#### `formatCurrency`
-
-Formats a number according to the locale in the country's official currency with support for various [notations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_notation).
-
-**Arguments**
-
-| Name      | Type                     | Examples                                                |
-| --------- | ------------------------ | ------------------------------------------------------- |
-| value     | number                   | `12345.67`, `-0.89`                                     |
-| locales?  | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| currency? | string                   | `'EUR'`, `'BRL'`, `'USD'`                               |
-| options?  | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
-
-**Examples**
-
-```ts
-import { formatCurrency } from '@sumup/intl';
-
-formatCurrency(12345.67, 'de-DE'); // '12.345,67 €'
-formatCurrency(89, 'ja-JP', 'JPY'); // '￥89'
-formatCurrency(16, 'en-GB', null, { currencyDisplay: 'name' }); // '16.00 British pounds'
-```
-
-### Format as parts
-
-#### `formatNumberToParts`
-
-Formats a number according to the locale with support for various [styles, units](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_style_and_unit), and [notations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_notation).
-
-**Arguments**
-
-| Name     | Type                     | Examples                                                |
-| -------- | ------------------------ | ------------------------------------------------------- |
-| value    | number                   | `12345.67`, `-0.89`                                     |
-| locales? | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| options? | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
-
-```ts
-import { formatNumberToParts } from '@sumup/intl';
-
-formatNumberToParts(12345.67, 'de-DE');
-// [
-//   { type: "integer", value: "12" },
-//   { type: "group", value: "." },
-//   { type: "integer", value: "345" },
-//   { type: "decimal", value: "," },
-//   { type: "fraction", value: "67" },
-// ]
-
-formatNumberToParts(-0.89, ['ban', 'id']);
-// [
-//   { type: "minusSign", value: "-" },
-//   { type: "integer", value: "0" },
-//   { type: "decimal", value: "," },
-//   { type: "fraction", value: "89" },
-// ]
-
-formatNumberToParts(16, 'en-GB', {
-  style: 'unit',
-  unit: 'liter',
-  unitDisplay: 'long',
-});
-// [
-//   { type: "integer", value: "16" },
-//   { type: "literal", value: " " },
-//   { type: "unit", value: "litres" },
-// ]
-```
-
-#### `formatCurrencyToParts`
-
-Formats a number according to the locale in the country's official currency with support for various [notations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_notation).
-
-**Arguments**
-
-| Name      | Type                     | Examples                                                |
-| --------- | ------------------------ | ------------------------------------------------------- |
-| value     | number                   | `12345.67`, `-0.89`                                     |
-| locales?  | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| currency? | string                   | `'EUR'`, `'BRL'`, `'USD'`                               |
-| options?  | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
-
-**Examples**
-
-```ts
-import { formatCurrencyToParts } from '@sumup/intl';
-
-formatCurrencyToParts(12345.67, 'de-DE');
-// [
-//   { type: "integer", value: "12" },
-//   { type: "group", value: "." },
-//   { type: "integer", value: "345" },
-//   { type: "decimal", value: "," },
-//   { type: "fraction", value: "67" },
-//   { type: "literal", value: " " },
-//   { type: "currency", value: "€" },
-// ]
-
-formatCurrencyToParts(-89, 'ja-JP', 'JPY');
-// [
-//   { type: "minusSign", value: "-" },
-//   { type: "currency", value: "￥" },
-//   { type: "integer", value: "89" },
-// ]
-
-formatCurrencyToParts(16, 'en-GB', null, { currencyDisplay: 'name' });
-// [
-//   { type: "integer", value: "16" },
-//   { type: "decimal", value: "." },
-//   { type: "fraction", value: "00" },
-//   { type: "literal", value: " " },
-//   { type: "currency", value: "British pounds" },
-// ]
-```
-
-### Resolve format
-
-#### `resolveNumberFormat`
-
-Resolves the locale and collation options that are used to format a number.
-
-**Arguments**
-
-| Name     | Type                     | Examples                                                |
-| -------- | ------------------------ | ------------------------------------------------------- |
-| locales? | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| options? | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
-
-**Examples**
-
-```ts
-import { resolveNumberFormat } from '@sumup/intl';
-
-resolveNumberFormat();
-// {
-//   'locale': 'en-US',
-//   'numberingSystem': 'latn',
-//   'style': 'decimal',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 0,
-//   'maximumFractionDigits': 3,
-//   'useGrouping': true,
-//   'groupDelimiter': ',',
-//   'decimalDelimiter': '.',
-// }
-
-resolveNumberFormat(['ban', 'id']);
-// {
-//   'locale': 'id',
-//   'numberingSystem': 'latn',
-//   'style': 'decimal',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 0,
-//   'maximumFractionDigits': 3,
-//   'useGrouping': true,
-//   'groupDelimiter': '.',
-//   'decimalDelimiter': ',',
-// }
-
-resolveNumberFormat('en-GB', {
-  style: 'unit',
-  unit: 'liter',
-  unitDisplay: 'long',
-});
-// {
-//   'locale': 'en-GB',
-//   'numberingSystem': 'latn',
-//   'style': 'unit',
-//   'unit': 'liter',
-//   'unitDisplay': 'long',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 0,
-//   'maximumFractionDigits': 3,
-//   'useGrouping': true,
-//   'notation': 'standard',
-//   'signDisplay': 'auto',
-//   'groupDelimiter': ',',
-//   'decimalDelimiter': '.',
-// }
-```
-
-#### `resolveCurrencyFormat`
-
-Resolves the locale and collation options that are used to format a number in the country's official currency.
-
-**Arguments**
-
-| Name      | Type                     | Examples                                                |
-| --------- | ------------------------ | ------------------------------------------------------- |
-| locales?  | string \| string[]       | `'de-DE'`, `'DE'`, `'zh-Hans-CN'`, `['de-AT', 'de-DE']` |
-| currency? | string                   | `'EUR'`, `'BRL'`, `'USD'`                               |
-| options?  | Intl.NumberFormatOptions | `{ style: 'unit', unit: 'mile-per-hour' }`              |
-
-**Examples**
-
-```ts
-import { resolveCurrencyFormat } from '@sumup/intl';
-
-resolveCurrencyFormat();
-// {
-//   'locale': 'en-US',
-//   'numberingSystem': 'latn',
-//   'style': 'currency',
-//   'currency': 'USD',
-//   'currencyDisplay': 'symbol',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 2,
-//   'maximumFractionDigits': 2,
-//   'useGrouping': true,
-//   'groupDelimiter': '.',
-//   'decimalDelimiter': ',',
-//   'currencySymbol': '$',
-//   'currencyPosition': 'prefix',
-// }
-
-resolveCurrencyFormat('ja-JP');
-// {
-//   'locale': 'ja-JP',
-//   'numberingSystem': 'latn',
-//   'style': 'currency',
-//   'currency': 'JPY',
-//   'currencyDisplay': 'symbol',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 0,
-//   'maximumFractionDigits': 0,
-//   'useGrouping': true,
-//   'groupDelimiter': ',',
-//   'decimalDelimiter': undefined,
-//   'currencySymbol': '￥',
-//   'currencyPosition': 'prefix',
-// }
-
-resolveCurrencyFormat('en-GB', { currencyDisplay: 'name' });
-// {
-//   'locale': 'en-GB',
-//   'numberingSystem': 'latn',
-//   'style': 'currency',
-//   'currency': 'GBP',
-//   'currencyDisplay': 'symbol',
-//   'minimumIntegerDigits': 1,
-//   'minimumFractionDigits': 2,
-//   'maximumFractionDigits': 2,
-//   'useGrouping': true,
-//   'groupDelimiter': ',',
-//   'decimalDelimiter': '.',
-//   'currencySymbol': 'British pounds',
-//   'currencyPosition': 'suffix',
-// }
-```
-
-### Constants
-
-#### `isNumberFormatSupported`
-
-Whether the `Intl` and `Intl.NumberFormat` APIs are supported by the runtime.
-
-```ts
-const isNumberFormatSupported: boolean;
-```
-
-#### `isNumberFormatToPartsSupported`
-
-Whether the `Intl`, `Intl.NumberFormat`, and `Intl.NumberFormat.formatToParts` APIs are supported by the runtime.
-
-```ts
-const isNumberFormatToPartsSupported: boolean;
-```
-
-#### `CURRENCIES`
-
-An object that maps a 2 char country code to its official 3 char currency code. [View all supported countries](https://github.com/sumup-oss/intl-js/blob/main/src/data/currencies.ts).
-
-```ts
-const CURRENCIES: { [country: string]: string };
-```
+- [CURRENCIES](https://github.com/sumup-oss/intl-js/wiki/Exports#currencies)
+- [isNumberFormatSupported](https://github.com/sumup-oss/intl-js/wiki/Exports#isnumberformatsupported)
+- [isNumberFormatToPartsSupported](https://github.com/sumup-oss/intl-js/wiki/Exports#isnumberformattopartssupported)
 
 ## Code of Conduct
 
@@ -361,6 +74,6 @@ If you feel another member of the community violated our CoC or you are experien
 
 ![SumUp logo](https://raw.githubusercontent.com/sumup-oss/assets/master/sumup-logo.svg?sanitize=true)
 
-[SumUp](https://sumup.com) is a mobile-point of sale provider. It is our mission to make easy and fast card payments a reality across the _entire_ world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia, and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Go, Java, Erlang, Elixir, and more.
+[SumUp](https://sumup.com) is a mobile point-of-sale provider. It is our mission to make easy and fast card payments a reality across the _entire_ world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia, and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Go, Java, Erlang, Elixir, and more.
 
 Want to come work with us? [Head to our careers page](https://sumup.com/careers) to find out more.
diff --git a/package.json b/package.json
@@ -29,6 +29,7 @@
     "build": "yarn build:es && yarn build:cjs",
     "build:es": "tsc",
     "build:cjs": "tsc --project tsconfig.cjs.json",
+    "docs": "typedoc",
     "lint": "foundry run eslint . --ext .js,.jsx,.ts,.tsx",
     "lint:fix": "yarn lint --fix",
     "lint:ci": "yarn lint --format github",
@@ -54,6 +55,9 @@
     "jest-github-reporter": "^1.0.2",
     "license-checker": "^25.0.1",
     "ts-jest": "^29.0.3",
+    "typedoc": "^0.23.16",
+    "typedoc-github-wiki-theme": "^1.0.1",
+    "typedoc-plugin-markdown": "^3.13.6",
     "typescript": "^4.3.2"
   }
 }