3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-01 10:22:30 +02:00
Code Issues Projects Releases Packages Wiki Activity

misc(v2): clean up comments in code (#2294)

Browse source
This commit is contained in:
Yangshun Tay 2020-02-18 21:29:23 +08:00 • committed by GitHub
parent d7f3dff6e6
commit 996b115199
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
45 changed files with 234 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

34
packages/docusaurus-plugin-content-docs/src/index.ts
View file

@ -71,7 +71,7 @@ export default function pluginContentDocs(
'docusaurus-plugin-content-docs',
);
// Versioning
// Versioning.
const env = loadEnv(siteDir);
const {versioning} = env;
const {
@ -128,7 +128,7 @@ export default function pluginContentDocs(
const docsMetadataRaw: DocsMetadataRaw = {};
const docsPromises = [];
// Metadata for default/ master docs files.
// Metadata for default/master docs files.
const docsFiles = await globby(include, {
cwd: docsDir,
});
@ -147,7 +147,7 @@ export default function pluginContentDocs(
),
);
// Metadata for versioned docs
// Metadata for versioned docs.
if (versioning.enabled) {
const versionedGlob = _.flatten(
include.map(pattern =>
@ -173,7 +173,7 @@ export default function pluginContentDocs(
);
}
// Load the sidebars & create docs ordering
// Load the sidebars and create docs ordering.
const sidebarPaths = [
sidebarPath,
...versionsNames.map(
@ -185,7 +185,7 @@ export default function pluginContentDocs(
await Promise.all(docsPromises);
// Construct inter-metadata relationship in docsMetadata
// Construct inter-metadata relationship in docsMetadata.
const docsMetadata: DocsMetadata = {};
const permalinkToSidebar: PermalinkToSidebar = {};
const versionToSidebars: VersionToSidebars = {};
@ -211,7 +211,7 @@ export default function pluginContentDocs(
next,
};
// sourceToPermalink and permalinkToSidebar mapping
// sourceToPermalink and permalinkToSidebar mapping.
const {source, permalink, version} = docsMetadataRaw[currentID];
sourceToPermalink[source] = permalink;
if (sidebar) {
@ -255,8 +255,9 @@ export default function pluginContentDocs(
}
};
// Transform the sidebar so that all sidebar item will be in the form of 'link' or 'category' only
// This is what will be passed as props to the UI component
// Transform the sidebar so that all sidebar item will be in the
// form of 'link' or 'category' only.
// This is what will be passed as props to the UI component.
const docsSidebars: DocsSidebar = Object.entries(loadedSidebars).reduce(
(acc: DocsSidebar, [sidebarId, sidebarItems]) => {
acc[sidebarId] = sidebarItems.map(normalizeItem);
@ -290,10 +291,12 @@ export default function pluginContentDocs(
const routes = await Promise.all(
metadataItems.map(async metadataItem => {
await createData(
// Note that this created data path must be in sync with metadataPath provided to mdx-loader
// Note that this created data path must be in sync with
// metadataPath provided to mdx-loader.
`${docuHash(metadataItem.source)}.json`,
JSON.stringify(metadataItem, null, 2),
);
return {
path: metadataItem.permalink,
component: docItemComponent,
@ -304,6 +307,7 @@ export default function pluginContentDocs(
};
}),
);
return routes.sort((a, b) =>
a.path > b.path ? 1 : b.path > a.path ? -1 : 0,
);
@ -331,8 +335,8 @@ export default function pluginContentDocs(
});
};
// If versioning is enabled, we cleverly chunk the generated routes to be by version
// and pick only needed base metadata
// If versioning is enabled, we cleverly chunk the generated routes
// to be by version and pick only needed base metadata.
if (versioning.enabled) {
const docsMetadataByVersion = _.groupBy(
Object.values(content.docsMetadata),
@ -365,8 +369,9 @@ export default function pluginContentDocs(
version,
};
// We want latest version route config to be placed last in the generated routeconfig.
// Otherwise, `/docs/next/foo` will match `/docs/:route` instead of `/docs/next/:route`
// We want latest version route config to be placed last in the
// generated routeconfig. Otherwise, `/docs/next/foo` will match
// `/docs/:route` instead of `/docs/next/:route`.
return addBaseRoute(
docsBaseRoute,
docsBaseMetadata,
@ -410,7 +415,8 @@ export default function pluginContentDocs(
remarkPlugins,
rehypePlugins,
metadataPath: (mdxPath: string) => {
// Note that metadataPath must be the same/ in-sync as the path from createData for each MDX
// Note that metadataPath must be the same/in-sync as
// the path from createData for each MDX.
const aliasedSource = aliasedSitePath(mdxPath, siteDir);
return path.join(
dataDir,

3
packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
View file

@ -31,7 +31,8 @@ export default async function getFileLastUpdate(
: {timestamp: +temp[1], author: temp[2]};
}
// Wrap in try/catch in case the shell commands fail (e.g. project doesn't use Git, etc).
// Wrap in try/catch in case the shell commands fail
// (e.g. project doesn't use Git, etc).
try {
if (!shell.which('git')) {
if (!showedGitRequirementError) {

1
packages/docusaurus-plugin-content-docs/src/markdown/linkify.ts
View file

@ -64,6 +64,7 @@ export default function(
}
return modifiedLine;
});
content = lines.join('\n');
}

13
packages/docusaurus-plugin-content-docs/src/metadata.ts
View file

@ -32,7 +32,7 @@ async function lastUpdated(
): Promise<LastUpdateData> {
const {showLastUpdateAuthor, showLastUpdateTime} = options;
if (showLastUpdateAuthor || showLastUpdateTime) {
// Use fake data in dev for faster development
// Use fake data in dev for faster development.
const fileLastUpdateData =
process.env.NODE_ENV === 'production'
? await lastUpdate(filePath)
@ -49,6 +49,7 @@ async function lastUpdated(
};
}
}
return {};
}
@ -83,7 +84,7 @@ export default async function processMetadata({
}
}
// The version portion of the url path. Eg: 'next', '1.0.0', and ''
// The version portion of the url path. Eg: 'next', '1.0.0', and ''.
const versionPath =
version && version !== versioning.latestVersion ? version : '';
@ -112,7 +113,7 @@ export default async function processMetadata({
const description: string = frontMatter.description || excerpt;
// The last portion of the url path. Eg: 'foo/bar', 'bar'
// The last portion of the url path. Eg: 'foo/bar', 'bar'.
const routePath =
version && version !== 'next'
? id.replace(new RegExp(`^version-${version}/`), '')
@ -126,8 +127,10 @@ export default async function processMetadata({
const {lastUpdatedAt, lastUpdatedBy} = await lastUpdatedPromise;
// Assign all of object properties during instantiation (if possible) for NodeJS optimization
// Adding properties to object after instantiation will cause hidden class transitions.
// Assign all of object properties during instantiation (if possible) for
// NodeJS optimization.
// Adding properties to object after instantiation will cause hidden
// class transitions.
const metadata: MetadataRaw = {
id,
title,

14
packages/docusaurus-plugin-content-docs/src/sidebars.ts
View file

@ -18,7 +18,7 @@ import {
} from './types';
/**
* Check that item contains only allowed keys
* Check that item contains only allowed keys.
*/
function assertItem(item: Object, keys: string[]): void {
const unknownKeys = Object.keys(item).filter(
@ -72,8 +72,8 @@ function assertIsLink(item: any): asserts item is SidebarItemLink {
}
/**
* Normalizes recursively item and all its children. Ensures, that at the end
* each item will be an object with the corresponding type
* Normalizes recursively item and all its children. Ensures that at the end
* each item will be an object with the corresponding type.
*/
function normalizeItem(item: SidebarItemRaw): SidebarItem {
if (typeof item === 'string') {
@ -102,7 +102,7 @@ function normalizeItem(item: SidebarItemRaw): SidebarItem {
}
/**
* Converts sidebars object to mapping to arrays of sidebar item objects
* Converts sidebars object to mapping to arrays of sidebar item objects.
*/
function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
return Object.entries(sidebars).reduce(
@ -110,7 +110,7 @@ function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
let normalizedSidebar: SidebarItemRaw[];
if (!Array.isArray(sidebar)) {
// convert sidebar to a more generic structure
// Convert sidebar to a more generic structure.
normalizedSidebar = Object.entries(sidebar).map(([label, items]) => ({
type: 'category',
label,
@ -129,11 +129,13 @@ function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
}
export default function loadSidebars(sidebarPaths?: string[]): Sidebar {
// We don't want sidebars to be cached because of hotreloading.
// We don't want sidebars to be cached because of hot reloading.
let allSidebars: SidebarRaw = {};
if (!sidebarPaths || !sidebarPaths.length) {
return {} as Sidebar;
}
sidebarPaths.map(sidebarPath => {
if (sidebarPath && fs.existsSync(sidebarPath)) {
const sidebar = importFresh(sidebarPath) as SidebarRaw;

17
packages/docusaurus-plugin-content-docs/src/version.ts
View file

@ -25,18 +25,21 @@ export function docsVersion(
'No version tag specified!. Pass the version you wish to create as an argument. Ex: 1.0.0',
);
}
if (version.includes('/') || version.includes('\\')) {
throw new Error(
`Invalid version tag specified! Do not include slash (/) or (\\). Try something like: 1.0.0`,
);
}
if (version.length > 32) {
throw new Error(
'Invalid version tag specified! Length must <= 32 characters. Try something like: 1.0.0',
);
}
// Since we are going to create `version-${version}` folder, we need to make sure its a valid path name
// Since we are going to create `version-${version}` folder, we need to make
// sure it's a valid pathname.
if (/[<>:"\/\\|?*\x00-\x1F]/g.test(version)) {
throw new Error(
'Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0',
@ -49,14 +52,14 @@ export function docsVersion(
);
}
// Load existing versions
// Load existing versions.
let versions = [];
const versionsJSONFile = getVersionsJSONFile(siteDir);
if (fs.existsSync(versionsJSONFile)) {
versions = JSON.parse(fs.readFileSync(versionsJSONFile, 'utf8'));
}
// Check if version already exist
// Check if version already exists.
if (versions.includes(version)) {
throw new Error(
'This version already exists!. Use a version tag that does not already exist.',
@ -65,7 +68,7 @@ export function docsVersion(
const {path: docsPath, sidebarPath} = options;
// Copy docs files
// Copy docs files.
const docsDir = path.join(siteDir, docsPath);
if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
const versionedDir = getVersionedDocsDir(siteDir);
@ -75,11 +78,11 @@ export function docsVersion(
throw new Error('There is no docs to version !');
}
// Load current sidebar and create a new versioned sidebars file
// Load current sidebar and create a new versioned sidebars file.
if (fs.existsSync(sidebarPath)) {
const loadedSidebars: Sidebar = loadSidebars([sidebarPath]);
// Transform id in original sidebar to versioned id
// Transform id in original sidebar to versioned id.
const normalizeItem = (item: SidebarItem): SidebarItem => {
switch (item.type) {
case 'category':
@ -117,7 +120,7 @@ export function docsVersion(
);
}
// update versions.json file
// Update versions.json file.
versions.unshift(version);
fs.ensureDirSync(path.dirname(versionsJSONFile));
fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);