refactor(content-docs): split version handling into several files (#7140

) * refactor(content-docs): split version handling into several files * fix test * increase timeout
facebook · Apr 9, 2022 · 96fbcb3 · 96fbcb3
1 parent 7d44961
commit 96fbcb3
Show file tree

Hide file tree

Showing 12 changed files with 618 additions and 698 deletions.
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts
@@ -33,6 +33,8 @@ import type {Optional} from 'utility-types';
 import {createSlugger, posixPath, DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import {createSidebarsUtils} from '../sidebars/utils';
 
+jest.setTimeout(15000);
+
 const fixtureDir = path.join(__dirname, '__fixtures__');
 
 const createFakeDocFile = ({

diff --git a/packages/docusaurus-plugin-content-docs/src/cli.ts b/packages/docusaurus-plugin-content-docs/src/cli.ts
@@ -7,14 +7,15 @@
 
 import {
   getVersionsFilePath,
-  getVersionedDocsDirPath,
-  getVersionedSidebarsDirPath,
+  getVersionDocsDirPath,
+  getVersionSidebarsPath,
   getDocsDirPathLocalized,
-} from './versions';
+} from './versions/files';
+import {validateVersionName} from './versions/validation';
 import fs from 'fs-extra';
 import path from 'path';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
-import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
+import {loadSidebarsFileUnsafe} from './sidebars';
 import {CURRENT_VERSION_NAME} from './constants';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
@@ -42,13 +43,8 @@ async function createVersionedSidebarFile({
   const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
-    const newSidebarFile = path.join(
-      versionedSidebarsDir,
-      `version-${version}-sidebars.json`,
-    );
     await fs.outputFile(
-      newSidebarFile,
+      getVersionSidebarsPath(siteDir, pluginId, version),
       `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
@@ -57,7 +53,7 @@ async function createVersionedSidebarFile({
 
 // Tests depend on non-default export for mocking.
 export async function cliDocsVersionCommand(
-  version: string | null | undefined,
+  version: string,
   {id: pluginId, path: docsPath, sidebarPath}: PluginOptions,
   {siteDir, i18n}: LoadContext,
 ): Promise<void> {
@@ -66,44 +62,18 @@ export async function cliDocsVersionCommand(
   const pluginIdLogPrefix =
     pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
 
-  if (!version) {
-    throw new Error(
-      `${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`,
-    );
-  }
-
-  if (version.includes('/') || version.includes('\\')) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`,
-    );
-  }
-
-  if (version.length > 32) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`,
-    );
-  }
-
-  // Since we are going to create `version-${version}` folder, we need to make
-  // sure it's a valid pathname.
-  // eslint-disable-next-line no-control-regex
-  if (/[<>:"|?*\x00-\x1F]/.test(version)) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`,
-    );
-  }
-
-  if (/^\.\.?$/.test(version)) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`,
-    );
+  try {
+    validateVersionName(version);
+  } catch (e) {
+    logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+    throw e;
   }
 
   // Load existing versions.
   let versions = [];
   const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
   if (await fs.pathExists(versionsJSONFile)) {
-    versions = JSON.parse(await fs.readFile(versionsJSONFile, 'utf8'));
+    versions = await fs.readJSON(versionsJSONFile);
   }
 
   // Check if version already exists.
@@ -146,10 +116,7 @@ export async function cliDocsVersionCommand(
 
       const newVersionDir =
         locale === i18n.defaultLocale
-          ? path.join(
-              getVersionedDocsDirPath(siteDir, pluginId),
-              `version-${version}`,
-            )
+          ? getVersionDocsDirPath(siteDir, pluginId, version)
           : getDocsDirPathLocalized({
               siteDir,
               locale,
@@ -164,7 +131,7 @@ export async function cliDocsVersionCommand(
     siteDir,
     pluginId,
     version,
-    sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
+    sidebarPath,
   });
 
   // Update versions.json file.

diff --git a/packages/docusaurus-plugin-content-docs/src/constants.ts b/packages/docusaurus-plugin-content-docs/src/constants.ts
@@ -5,9 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// The name of the version at the root of your site (website/docs)
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 export const CURRENT_VERSION_NAME = 'current';
-
+/** All doc versions are stored here by version names */
 export const VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
 export const VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 export const VERSIONS_JSON_FILE = 'versions.json';
diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -20,7 +20,7 @@ import {
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import type {LoadContext, Plugin} from '@docusaurus/types';
-import {loadSidebars} from './sidebars';
+import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
 import {
   readVersionDocs,
@@ -64,6 +64,8 @@ export default async function pluginContentDocs(
   options: PluginOptions,
 ): Promise<Plugin<LoadedContent>> {
   const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
+  // Mutate options to resolve sidebar path according to siteDir
+  options.sidebarPath = resolveSidebarPathOption(siteDir, options.sidebarPath);
 
   const versionsMetadata = await readVersionsMetadata({context, options});
 

diff --git a/packages/docusaurus-plugin-content-docs/src/server-export.ts b/packages/docusaurus-plugin-content-docs/src/server-export.ts
@@ -18,7 +18,5 @@ export {
   getDefaultVersionBanner,
   getVersionBadge,
   getVersionBanner,
-  getVersionsFilePath,
-  readVersionsFile,
-  readVersionNames,
 } from './versions';
+export {readVersionNames} from './versions/files';
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts
@@ -32,7 +32,6 @@ export const DefaultSidebars: SidebarsConfig = {
 export const DisabledSidebars: SidebarsConfig = {};
 
 // If a path is provided, make it absolute
-// use this before loadSidebars()
 export function resolveSidebarPathOption(
   siteDir: string,
   sidebarPathOption: PluginOptions['sidebarPath'],
@@ -93,7 +92,6 @@ export async function loadSidebarsFileUnsafe(
   return importFresh(sidebarFilePath);
 }
 
-// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
   options: SidebarProcessorParams,