Skip to content

Commit 0415d2b

Browse files
andrii-bodnarandrii-bodnar
authored
docs: upgrade Docusaurus to v3, improve automatic API docs (#100)
1 parent 62bc9fb commit 0415d2b

File tree

9 files changed

+22377
-17569
lines changed

9 files changed

+22377
-17569
lines changed

‎.github/workflows/docs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515
- name: Setup Node.js
1616
uses: actions/setup-node@v4
1717
with:
18-
node-version: 18
18+
node-version: 20
1919
cache: 'npm'
2020

2121
- name: Install dependencies

‎src/index.ts

+47-37
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ export default class OtaClient {
2121
private locale?: string;
2222

2323
/**
24-
* @param distributionHash hash of released Crowdin project distribution
25-
* @param config client config
24+
* @param distributionHash Hash of released Crowdin project distribution
25+
* @param config Client config
2626
*/
2727
constructor(private distributionHash: string, config?: ClientConfig) {
2828
this.httpClient = config?.httpClient || new FetchHttpClient();
@@ -33,58 +33,60 @@ export default class OtaClient {
3333
}
3434

3535
/**
36-
* Get the distribution hash
36+
* Get the distribution hash.
3737
*
38-
* @category Helper
38+
* @category Helper Methods
3939
*/
4040
getHash(): string {
4141
return this.distributionHash;
4242
}
4343

4444
/**
4545
* Define the global language for the client instance.
46-
* Default language code to be used if language was not passed as an input argument of the method
46+
* Default language code to be used if language was not passed as an input argument of the method.
4747
*
48-
* @param languageCode {@link https://developer.crowdin.com/language-codes Language Code}
49-
* @category Helper
48+
* @category Helper Methods
49+
* @param languageCode {@link https://support.crowdin.com/developer/language-codes/ Language Code}
5050
*/
5151
setCurrentLocale(languageCode?: string): void {
5252
this.locale = languageCode;
5353
}
5454

5555
/**
56-
* Get the current locale
56+
* Get the current locale of the client instance.
5757
*
58-
* @category Helper
58+
* @category Helper Methods
5959
*/
6060
getCurrentLocale(): string | undefined {
6161
return this.locale;
6262
}
6363

6464
/**
65-
* Get manifest timestamp of distribution
65+
* Get distribution's manifest timestamp.
6666
*
67-
* @category Helper
67+
* @category Helper Methods
6868
*/
6969
async getManifestTimestamp(): Promise<number> {
7070
return (await this.manifest).timestamp;
7171
}
7272

7373
/**
74-
* List distribution's files content
74+
* List distribution's files content.
7575
*
76-
* @category Content Management
76+
* @category Content Management Methods
77+
*
78+
* @returns An object mapping {@link https://support.crowdin.com/developer/language-codes/ Language Code} to arrays of strings: `{[languageCode: string]: string[]}`
7779
*/
7880
async getContent(): Promise<Manifest['content']> {
7981
return (await this.manifest).content;
8082
}
8183

8284
/**
83-
* List distribution's files content for a specific language
85+
* List distribution's files content for a specific language.
8486
*
85-
* @param languageCode {@link https://developer.crowdin.com/language-codes Language Code}
87+
* @category Content Management Methods
8688
*
87-
* @category Content Management
89+
* @param languageCode {@link https://support.crowdin.com/developer/language-codes/ Language Code}
8890
*/
8991
async getLanguageContent(languageCode?: string): Promise<string[]> {
9092
const language = this.getLanguageCode(languageCode);
@@ -93,18 +95,20 @@ export default class OtaClient {
9395
}
9496

9597
/**
96-
* List Crowdin project language codes
98+
* List Crowdin project {@link https://support.crowdin.com/developer/language-codes/ language codes}.
9799
*
98-
* @category Helper
100+
* @category Helper Methods
99101
*/
100102
async listLanguages(): Promise<string[]> {
101103
return Object.keys(await this.getContent());
102104
}
103105

104106
/**
105-
* Returns all translations per each language code
107+
* Get all translations for all languages.
108+
*
109+
* @category Content Management Methods
106110
*
107-
* @category Content Management
111+
* @returns All translations per each language code
108112
*/
109113
async getTranslations(): Promise<Translations> {
110114
const languages = await this.listLanguages();
@@ -118,11 +122,12 @@ export default class OtaClient {
118122
}
119123

120124
/**
121-
* Returns translations for each file in the distribution for a given language
125+
* Get translations for a specific language.
122126
*
123-
* @param languageCode {@link https://developer.crowdin.com/language-codes Language Code}
127+
* @category Content Management Methods
124128
*
125-
* @category Content Management
129+
* @param languageCode {@link https://support.crowdin.com/developer/language-codes/ Language Code}
130+
* @returns Translations for each file in the distribution for a given language (content)
126131
*/
127132
async getLanguageTranslations(languageCode?: string): Promise<LanguageTranslations[]> {
128133
const language = this.getLanguageCode(languageCode);
@@ -137,11 +142,12 @@ export default class OtaClient {
137142
}
138143

139144
/**
140-
* Returns translations for a specific file (content)
145+
* Get translations for a specific file.
141146
*
142-
* @param file file content path
147+
* @category Content Management Methods
143148
*
144-
* @category Content Management
149+
* @param file file content path
150+
* @returns Translations for a specific file (content)
145151
*/
146152
async getFileTranslations(file: string): Promise<string | any | null> {
147153
const content = await this.getContent();
@@ -155,9 +161,11 @@ export default class OtaClient {
155161
}
156162

157163
/**
158-
* Returns translation strings from json-based files for all languages
164+
* Get all translation strings for all languages.
159165
*
160-
* @category Strings Management
166+
* @category Strings Management Methods
167+
*
168+
* @returns Translation strings from json-based files for all languages
161169
*/
162170
async getStrings(): Promise<LanguageStrings> {
163171
const content = await this.getJsonFiles();
@@ -171,11 +179,12 @@ export default class OtaClient {
171179
}
172180

173181
/**
174-
* Returns translation strings from json-based files for a given language
182+
* Get translation strings for a specific language.
175183
*
176-
* @param languageCode {@link https://developer.crowdin.com/language-codes Language Code}
184+
* @category Strings Management Methods
177185
*
178-
* @category Strings Management
186+
* @param languageCode {@link https://support.crowdin.com/developer/language-codes/ Language Code}
187+
* @returns Translation strings from json-based files for a given language
179188
*/
180189
async getStringsByLocale(languageCode?: string): Promise<any> {
181190
const language = this.getLanguageCode(languageCode);
@@ -184,12 +193,13 @@ export default class OtaClient {
184193
}
185194

186195
/**
187-
* Returns translation string for language for given key
196+
* Get translation string for a specific key.
188197
*
189-
* @param key path to the translation string in json file
190-
* @param languageCode {@link https://developer.crowdin.com/language-codes Language Code}
198+
* @category Strings Management Methods
191199
*
192-
* @category Strings Management
200+
* @param key path to the translation string in json file
201+
* @param languageCode {@link https://support.crowdin.com/developer/language-codes/ Language Code}
202+
* @returns Translation string for language for given key
193203
*/
194204
async getStringByKey(key: string[] | string, languageCode?: string): Promise<string | any> {
195205
const strings = await this.getStringsByLocale(languageCode);
@@ -206,9 +216,9 @@ export default class OtaClient {
206216
}
207217

208218
/**
209-
* Clear the translation string cache
219+
* Clear the translation strings cache.
210220
*
211-
* @category Helper
221+
* @category Helper Methods
212222
*/
213223
clearStringsCache(): void {
214224
this.stringsCache = {};

‎src/model.ts

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* @module Types
3+
* @description This module contains the types used in the Crowdin OTA Client.
4+
*/
5+
16
export interface ClientConfig {
27
/**
38
* Specify your own http client. Default uses fetch

‎website/babel.config.js

-3
This file was deleted.

‎website/docusaurus.config.js ‎website/docusaurus.config.ts

+22-20
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,13 @@
1-
// @ts-check
2-
// Note: type annotations allow type checking and IDEs autocompletion
1+
import type { Config } from "@docusaurus/types";
2+
import type * as Preset from "@docusaurus/preset-classic";
3+
import { themes } from "prism-react-renderer";
4+
import { PluginOptions } from "@easyops-cn/docusaurus-search-local";
35

4-
const lightCodeTheme = require('prism-react-renderer/themes/github');
5-
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
6-
7-
/** @type {import('@docusaurus/types').Config} */
8-
const config = {
6+
const config: Config = {
97
title: 'Crowdin OTA JS Client',
108
tagline: 'JavaScript client library for Crowdin Over-The-Air Content Delivery',
119
favicon: 'img/favicon.ico',
1210

13-
// Set the production url of your site here
1411
url: 'https://crowdin.github.io/',
1512
baseUrl: '/ota-client-js',
1613
organizationName: 'crowdin',
@@ -27,8 +24,7 @@ const config = {
2724
presets: [
2825
[
2926
'classic',
30-
/** @type {import('@docusaurus/preset-classic').Options} */
31-
({
27+
{
3228
docs: {
3329
routeBasePath: '/',
3430
sidebarPath: require.resolve('./sidebars.js'),
@@ -45,7 +41,7 @@ const config = {
4541
theme: {
4642
customCss: require.resolve('./src/css/custom.css'),
4743
},
48-
}),
44+
} satisfies Preset.Options,
4945
],
5046
],
5147

@@ -56,15 +52,12 @@ const config = {
5652
hashed: true,
5753
docsRouteBasePath: '/',
5854
indexBlog: false,
59-
}),
55+
} satisfies PluginOptions),
6056
]
6157
],
6258

6359
themeConfig:
64-
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
6560
({
66-
// Replace with your project's social card
67-
// image: 'img/social-card.jpg',
6861
navbar: {
6962
title: 'Crowdin OTA JS Client',
7063
logo: {
@@ -125,19 +118,28 @@ const config = {
125118
copyright: `Copyright © ${new Date().getFullYear()} OTA JS Client, Crowdin.`,
126119
},
127120
prism: {
128-
theme: lightCodeTheme,
129-
darkTheme: darkCodeTheme,
121+
theme: themes.github,
122+
darkTheme: themes.dracula,
130123
},
131-
}),
124+
}) satisfies Preset.ThemeConfig,
132125

133126
plugins: [
134127
[
128+
// https://typedoc-plugin-markdown.org/plugins/docusaurus/quick-start
135129
'docusaurus-plugin-typedoc',
136130
{
131+
plugin: ['typedoc-plugin-rename-defaults'],
132+
entryPoints: ['../src/index.ts', '../src/model.ts'],
137133
entryPointStrategy: 'expand',
138-
entryPoints: ['../src/index.ts'],
134+
outputFileStrategy: 'members',
135+
flattenOutputFiles: true,
136+
membersWithOwnFile: ['Class'],
137+
parametersFormat: 'table',
138+
interfacePropertiesFormat: 'table',
139+
categoryOrder: ['Strings Management Methods', 'Content Management Methods', 'Helper Methods'],
140+
sort: 'source-order',
139141
tsconfig: '../tsconfig.json',
140-
plugin: ['typedoc-plugin-rename-defaults'],
142+
watch: process.env.TYPEDOC_WATCH,
141143
}
142144
]
143145
]

0 commit comments

Comments
 (0)