From edab7e07edfc15ee75dc16f38c6a7fcc10779ec7 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 6 Jan 2022 21:46:08 +0800 Subject: [PATCH] refactor(content-docs): make readVersionsMetadata async (#6277) * refactor(content-docs): make readVersionsMetadata async * fix tests --- .../src/__tests__/docs.test.ts | 4 +- .../src/__tests__/index.test.ts | 2 +- .../src/__tests__/versions.test.ts | 78 ++++++++--------- .../src/index.ts | 2 +- .../src/versions.ts | 84 ++++++++++--------- 5 files changed, 87 insertions(+), 83 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts index aa91234a06..4615dd0954 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -166,7 +166,7 @@ describe('simple site', () => { ...DEFAULT_OPTIONS, ...loadSiteOptions.options, }; - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ context, options, }); @@ -523,7 +523,7 @@ describe('versioned site', () => { ...DEFAULT_OPTIONS, ...loadSiteOptions.options, }; - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ context, options, }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts index 87e55c7a2e..e731187806 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts @@ -141,7 +141,7 @@ describe('sidebar', () => { Please set the docs \\"sidebarPath\\" field in your config file to: - a sidebars path that exists - false: to disable the sidebar - - undefined: for Docusaurus generates it automatically" + - undefined: for Docusaurus to generate it automatically" `); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts index ad4dba5a33..9ab0d973b0 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts @@ -91,7 +91,7 @@ describe('simple site', () => { test('readVersionsMetadata simple site', async () => { const {defaultOptions, defaultContext, vCurrent} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: defaultOptions, context: defaultContext, }); @@ -102,7 +102,7 @@ describe('simple site', () => { test('readVersionsMetadata simple site with base url', async () => { const {defaultOptions, defaultContext, vCurrent} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: defaultOptions, context: { ...defaultContext, @@ -122,7 +122,7 @@ describe('simple site', () => { test('readVersionsMetadata simple site with current version config', async () => { const {defaultOptions, defaultContext, vCurrent} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: { ...defaultOptions, versions: { @@ -155,20 +155,20 @@ describe('simple site', () => { test('readVersionsMetadata simple site with unknown lastVersion should throw', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: {...defaultOptions, lastVersion: 'unknownVersionName'}, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( - `"Docs option lastVersion=unknownVersionName is invalid. Available version names are: current"`, + ).rejects.toThrowErrorMatchingInlineSnapshot( + `"Docs option lastVersion: unknownVersionName is invalid. Available version names are: current"`, ); }); test('readVersionsMetadata simple site with unknown version configurations should throw', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -180,7 +180,7 @@ describe('simple site', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( + ).rejects.toThrowErrorMatchingInlineSnapshot( `"Invalid docs option \\"versions\\": unknown versions (unknownVersionName1,unknownVersionName2) found. Available version names are: current"`, ); }); @@ -188,26 +188,26 @@ describe('simple site', () => { test('readVersionsMetadata simple site with disableVersioning while single version should throw', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: {...defaultOptions, disableVersioning: true}, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( - `"Docs: using \\"disableVersioning=true\\" option on a non-versioned site does not make sense."`, + ).rejects.toThrowErrorMatchingInlineSnapshot( + `"Docs: using \\"disableVersioning: true\\" option on a non-versioned site does not make sense."`, ); }); test('readVersionsMetadata simple site without including current version should throw', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: {...defaultOptions, includeCurrentVersion: false}, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( - `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=false\\"."`, + ).rejects.toThrowErrorMatchingInlineSnapshot( + `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: false\\"."`, ); }); }); @@ -327,7 +327,7 @@ describe('versioned site, pluginId=default', () => { const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: defaultOptions, context: defaultContext, }); @@ -339,7 +339,7 @@ describe('versioned site, pluginId=default', () => { const {defaultOptions, defaultContext, v101, v100, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: {...defaultOptions, includeCurrentVersion: false}, context: defaultContext, }); @@ -356,7 +356,7 @@ describe('versioned site, pluginId=default', () => { const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: { ...defaultOptions, lastVersion: '1.0.0', @@ -410,7 +410,7 @@ describe('versioned site, pluginId=default', () => { const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: { ...defaultOptions, editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', @@ -454,7 +454,7 @@ describe('versioned site, pluginId=default', () => { const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: { ...defaultOptions, editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', @@ -498,7 +498,7 @@ describe('versioned site, pluginId=default', () => { test('readVersionsMetadata versioned site with onlyIncludeVersions option', async () => { const {defaultOptions, defaultContext, v101, vwithSlugs} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: { ...defaultOptions, // Order reversed on purpose: should not have any impact @@ -513,7 +513,7 @@ describe('versioned site, pluginId=default', () => { test('readVersionsMetadata versioned site with disableVersioning', async () => { const {defaultOptions, defaultContext, vCurrent} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: {...defaultOptions, disableVersioning: true}, context: defaultContext, }); @@ -534,7 +534,7 @@ describe('versioned site, pluginId=default', () => { test('readVersionsMetadata versioned site with all versions disabled', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -543,15 +543,15 @@ describe('versioned site, pluginId=default', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( - `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`, + ).rejects.toThrowErrorMatchingInlineSnapshot( + `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`, ); }); test('readVersionsMetadata versioned site with empty onlyIncludeVersions', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -559,7 +559,7 @@ describe('versioned site, pluginId=default', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( + ).rejects.toThrowErrorMatchingInlineSnapshot( `"Invalid docs option \\"onlyIncludeVersions\\": an empty array is not allowed, at least one version is needed."`, ); }); @@ -567,7 +567,7 @@ describe('versioned site, pluginId=default', () => { test('readVersionsMetadata versioned site with unknown versions in onlyIncludeVersions', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -575,7 +575,7 @@ describe('versioned site, pluginId=default', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( + ).rejects.toThrowErrorMatchingInlineSnapshot( `"Invalid docs option \\"onlyIncludeVersions\\": unknown versions (unknownVersion1,unknownVersion2) found. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`, ); }); @@ -583,7 +583,7 @@ describe('versioned site, pluginId=default', () => { test('readVersionsMetadata versioned site with lastVersion not in onlyIncludeVersions', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -592,7 +592,7 @@ describe('versioned site, pluginId=default', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( + ).rejects.toThrowErrorMatchingInlineSnapshot( `"Invalid docs option \\"lastVersion\\": if you use both the \\"onlyIncludeVersions\\" and \\"lastVersion\\" options, then \\"lastVersion\\" must be present in the provided \\"onlyIncludeVersions\\" array."`, ); }); @@ -604,12 +604,12 @@ describe('versioned site, pluginId=default', () => { invalid: 'json', })); - expect(() => { + await expect( readVersionsMetadata({ options: defaultOptions, context: defaultContext, - }); - }).toThrowErrorMatchingInlineSnapshot( + }), + ).rejects.toThrowErrorMatchingInlineSnapshot( `"The versions file should contain an array of versions! Found content: {\\"invalid\\":\\"json\\"}"`, ); mock.mockRestore(); @@ -682,7 +682,7 @@ describe('versioned site, pluginId=community', () => { test('readVersionsMetadata versioned site (community)', async () => { const {defaultOptions, defaultContext, vCurrent, v100} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: defaultOptions, context: defaultContext, }); @@ -693,7 +693,7 @@ describe('versioned site, pluginId=community', () => { test('readVersionsMetadata versioned site (community) with includeCurrentVersion=false', async () => { const {defaultOptions, defaultContext, v100} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: {...defaultOptions, includeCurrentVersion: false}, context: defaultContext, }); @@ -707,7 +707,7 @@ describe('versioned site, pluginId=community', () => { test('readVersionsMetadata versioned site (community) with disableVersioning', async () => { const {defaultOptions, defaultContext, vCurrent} = await loadSite(); - const versionsMetadata = readVersionsMetadata({ + const versionsMetadata = await readVersionsMetadata({ options: {...defaultOptions, disableVersioning: true}, context: defaultContext, }); @@ -728,7 +728,7 @@ describe('versioned site, pluginId=community', () => { test('readVersionsMetadata versioned site (community) with all versions disabled', async () => { const {defaultOptions, defaultContext} = await loadSite(); - expect(() => + await expect( readVersionsMetadata({ options: { ...defaultOptions, @@ -737,8 +737,8 @@ describe('versioned site, pluginId=community', () => { }, context: defaultContext, }), - ).toThrowErrorMatchingInlineSnapshot( - `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`, + ).rejects.toThrowErrorMatchingInlineSnapshot( + `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`, ); }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 1de2018fdf..8f751c0670 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -64,7 +64,7 @@ export default async function pluginContentDocs( ): Promise> { const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context; - const versionsMetadata = readVersionsMetadata({context, options}); + const versionsMetadata = await readVersionsMetadata({context, options}); const pluginId = options.id ?? DEFAULT_PLUGIN_ID; diff --git a/packages/docusaurus-plugin-content-docs/src/versions.ts b/packages/docusaurus-plugin-content-docs/src/versions.ts index 6389a9dad4..0cfa344058 100644 --- a/packages/docusaurus-plugin-content-docs/src/versions.ts +++ b/packages/docusaurus-plugin-content-docs/src/versions.ts @@ -87,11 +87,13 @@ function ensureValidVersionArray( versionArray.forEach(ensureValidVersionString); } -// TODO not easy to make async due to many deps -function readVersionsFile(siteDir: string, pluginId: string): string[] | null { +async function readVersionsFile( + siteDir: string, + pluginId: string, +): Promise { const versionsFilePath = getVersionsFilePath(siteDir, pluginId); - if (fs.existsSync(versionsFilePath)) { - const content = JSON.parse(fs.readFileSync(versionsFilePath, 'utf8')); + if (await fs.pathExists(versionsFilePath)) { + const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8')); ensureValidVersionArray(content); return content; } else { @@ -99,27 +101,26 @@ function readVersionsFile(siteDir: string, pluginId: string): string[] | null { } } -// TODO not easy to make async due to many deps -function readVersionNames( +async function readVersionNames( siteDir: string, options: Pick< PluginOptions, 'id' | 'disableVersioning' | 'includeCurrentVersion' >, -): string[] { - const versionFileContent = readVersionsFile(siteDir, options.id); +): Promise { + const versionFileContent = await readVersionsFile(siteDir, options.id); if (!versionFileContent && options.disableVersioning) { throw new Error( - `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`, + `Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`, ); } const versions = options.disableVersioning ? [] : versionFileContent ?? []; - // We add the current version at the beginning, unless - // - user don't want to - // - it's been explicitly added to versions.json + // We add the current version at the beginning, unless: + // - user don't want to; or + // - it's already been explicitly added to versions.json if ( options.includeCurrentVersion && !versions.includes(CURRENT_VERSION_NAME) @@ -129,7 +130,7 @@ function readVersionNames( if (versions.length === 0) { throw new Error( - `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`, + `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`, ); } @@ -174,13 +175,6 @@ function getVersionMetadataPaths({ > { const isCurrentVersion = versionName === CURRENT_VERSION_NAME; - const contentPath = isCurrentVersion - ? path.resolve(context.siteDir, options.path) - : path.join( - getVersionedDocsDirPath(context.siteDir, options.id), - `version-${versionName}`, - ); - const contentPathLocalized = getDocsDirPathLocalized({ siteDir: context.siteDir, locale: context.i18n.currentLocale, @@ -188,21 +182,27 @@ function getVersionMetadataPaths({ versionName, }); - function getSidebarFilePath() { - if (isCurrentVersion) { - return resolveSidebarPathOption(context.siteDir, options.sidebarPath); - } else { - return path.join( - getVersionedSidebarsDirPath(context.siteDir, options.id), - `version-${versionName}-sidebars.json`, - ); - } + if (isCurrentVersion) { + return { + contentPath: path.resolve(context.siteDir, options.path), + contentPathLocalized, + sidebarFilePath: resolveSidebarPathOption( + context.siteDir, + options.sidebarPath, + ), + }; } return { - contentPath, + contentPath: path.join( + getVersionedDocsDirPath(context.siteDir, options.id), + `version-${versionName}`, + ), contentPathLocalized, - sidebarFilePath: getSidebarFilePath(), + sidebarFilePath: path.join( + getVersionedSidebarsDirPath(context.siteDir, options.id), + `version-${versionName}-sidebars.json`, + ), }; } @@ -459,7 +459,7 @@ function checkVersionMetadataPaths({ Please set the docs "sidebarPath" field in your config file to: - a sidebars path that exists - false: to disable the sidebar -- undefined: for Docusaurus generates it automatically`); +- undefined: for Docusaurus to generate it automatically`); } } @@ -488,7 +488,7 @@ function checkVersionsOptions( !availableVersionNames.includes(options.lastVersion) ) { throw new Error( - `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`, + `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`, ); } const unknownVersionConfigNames = difference( @@ -531,9 +531,11 @@ function checkVersionsOptions( } } -// Filter versions according to provided options -// Note: we preserve the order in which versions are provided -// the order of the onlyIncludeVersions array does not matter +/** + * Filter versions according to provided options. + * Note: we preserve the order in which versions are provided; + * the order of the onlyIncludeVersions array does not matter + */ function filterVersions( versionNamesUnfiltered: string[], options: Pick, @@ -547,8 +549,7 @@ function filterVersions( } } -// TODO make this async (requires plugin init to be async) -export function readVersionsMetadata({ +export async function readVersionsMetadata({ context, options, }: { @@ -568,8 +569,11 @@ export function readVersionsMetadata({ | 'editUrl' | 'editCurrentVersion' >; -}): VersionMetadata[] { - const versionNamesUnfiltered = readVersionNames(context.siteDir, options); +}): Promise { + const versionNamesUnfiltered = await readVersionNames( + context.siteDir, + options, + ); checkVersionsOptions(versionNamesUnfiltered, options);