Skip to content

Commit

Permalink
feat: 馃幐 Docusaurus 3.0
Browse files Browse the repository at this point in the history
  • Loading branch information
prc5 committed Nov 27, 2023
1 parent f45c02b commit e14aea5
Show file tree
Hide file tree
Showing 10 changed files with 3,322 additions and 2,475 deletions.
19 changes: 10 additions & 9 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -79,14 +79,14 @@
"@types/react-dom": "^18.0.6",
"@types/rimraf": "^3.0.2",
"@types/turndown": "^5.0.1",
"@typescript-eslint/eslint-plugin": "^5.28.0",
"@typescript-eslint/parser": "^5.28.0",
"@typescript-eslint/eslint-plugin": "^6.13.0",
"@typescript-eslint/parser": "^6.13.0",
"@zerollup/ts-transform-paths": "^1.7.18",
"chalk": "^4.1.2",
"commitlint": "^17.0.2",
"eslint": "^8.17.0",
"eslint-config-airbnb": "^19.0.4",
"eslint-config-airbnb-typescript": "^17.0.0",
"eslint-config-airbnb-typescript": "^17.1.0",
"eslint-config-next": "12.1.6",
"eslint-config-prettier": "^8.5.0",
"eslint-config-react-app": "^7.0.1",
Expand Down Expand Up @@ -116,21 +116,22 @@
"ts-jest": "^28.0.5",
"ts-node": "~10.8.0",
"tslib": "^2.3.0",
"typescript": "^4.8.4"
"typescript": "^5.3.2"
},
"dependencies": {
"@docusaurus/plugin-content-docs": "2.0.0-beta.20",
"fs-extra": "^10.0.0",
"isomorphic-dompurify": "^0.23.0",
"mdast-util-from-markdown": "^2.0.0",
"mdast-util-mdx": "^3.0.0",
"mdx-mermaid": "^1.2.1",
"micromark-extension-mdxjs": "2.0.0",
"node-html-markdown": "^1.2.2",
"node-html-parser": "^6.1.1",
"remark-admonitions": "^1.2.1",
"remark-parse": "8.0.3",
"typedoc": "^0.23.17",
"typedoc-plugin-markdown": "^3.13.6",
"unified": "9.2.2",
"unist-util-visit": "2.0.3"
"typedoc": "^0.25.3",
"typedoc-plugin-markdown": "^3.17.1",
"unist-util-visit": "5.0.0"
},
"files": [
"dist"
Expand Down
12 changes: 9 additions & 3 deletions src/docs/docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export const buildDocs = async (
const { id, packages, tsConfigPath } = pluginOptions;
const isMonorepo = packages.length > 1;

if (isMonorepo) {
if (isMonorepo && pluginOptions.generateMdx) {
trace(`Generating monorepo page for ${pluginOptions.packages.length} packages`);
generateMonorepoPage(docsGenerationDir, pluginOptions);
}
Expand Down Expand Up @@ -76,8 +76,10 @@ export const buildDocs = async (
/**
* Generate package page from readme or custom setup
*/
trace(`Generating package page`, packageName);
generatePackagePage(packageDocsDir, packageOptions);
if (pluginOptions.generateMdx) {
trace(`Generating package page`, packageName);
generatePackagePage(packageDocsDir, packageOptions);
}

/**
* Scan and parse docs to json
Expand All @@ -91,6 +93,10 @@ export const buildDocs = async (
* Generate docs files
*/
await asyncForEach(packages, async (packageOptions) => {
if (!pluginOptions.generateMdx) {
return trace(`Skipping the docs generation, generateMdx option is set to false`);
}

const { packageName, docsJsonPaths, packageDocsDir } = getPackageOptions(
packages,
packageOptions,
Expand Down
5 changes: 3 additions & 2 deletions src/docs/generator/api-generator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ const docsExtension = ".mdx";

type ApiGeneratorProps = {
packageName: string;
parsedApiJsons: JSONOutput.ProjectReflection[];
parsedApiJsons: JSONOutput.DeclarationReflection[];
packageDocsDir: string;
docsGenerationDir: string;
pluginOptions: PluginOptions;
Expand All @@ -28,7 +28,8 @@ export const apiGenerator = ({

parsedApiJson.children?.forEach((reflection) => {
const { name } = reflection;
const kind = getKindName(reflection.kindString || "", name);
const kindString = "kindString" in reflection ? (reflection.kindString as string) : "";
const kind = getKindName(kindString || "", name);

if (!kind) {
return trace(`Module ${kind} not parsed. Missing type specification.`);
Expand Down
3 changes: 2 additions & 1 deletion src/docs/generator/utils/package.utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,8 @@ export const getPackageOptions = (
...packageDocsPaths.filter((pkgPath) => pkgPath !== packageDocsJsonPath),
];
// Package tsconfig file
const tsconfigPath = tsConfigPath ?? path.join(tsconfigDir, tsconfigName);
const tsconfigPath = tsConfigPath || path.join(tsconfigDir, tsconfigName);

// Generate meta
const pkgMeta: PkgMeta = {
title,
Expand Down
41 changes: 19 additions & 22 deletions src/docs/pages/presentation/monorepo.page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ const MonorepoPage: React.FC<{ options: PluginOptions }> = ({ options }) => {

const breadcrumbs = outDir.split("/").filter(Boolean);
if (breadcrumbs.length > 1) breadcrumbs.shift();
const dirPath = breadcrumbs.join("/");

return (
<>
Expand All @@ -29,28 +28,26 @@ sidebar_position: 1
<div className="api-docs__monorepo-row row api-row">
{packages.map((pkg, index) => (
<article className="api-docs__monorepo-column col col--6" key={index}>
<div className="api-docs__monorepo-card card margin-bottom--lg padding--lg pagination-nav__link">
<h2 className="api-docs__monorepo-card-title text--truncate api-card-title">
<img
loading="lazy"
src={pkg.logo}
alt=""
className="api-docs__monorepo-card-image"
width="24"
height="24"
/>
{pkg.title}
</h2>
<div className="api-docs__monorepo-card-more text--truncate pagination-nav__sublabel">
{`
[Show details 禄](${`/${path.join(dirPath, cleanFileName(pkg.title))}/index.mdx`})
`}
<a href={`/${path.join(outDir, cleanFileName(pkg.title))}`}>
<div className="api-docs__monorepo-card card margin-bottom--lg padding--lg pagination-nav__link">
<h2 className="api-docs__monorepo-card-title text--truncate api-card-title">
{pkg.logo && (
<img
loading="lazy"
src={pkg.logo}
alt=""
className="api-docs__monorepo-card-image"
width="24"
height="24"
/>
)}
{pkg.title}
</h2>
<div className="api-docs__monorepo-card-more text--truncate pagination-nav__sublabel">
Show details 禄
</div>
</div>
</div>
</a>
</article>
))}
</div>
Expand Down
70 changes: 43 additions & 27 deletions src/docs/parser/parser.ts
Original file line number Diff line number Diff line change
@@ -1,40 +1,56 @@
import * as TypeDoc from "typedoc";
import { Application, TSConfigReader, TypeDocReader } from "typedoc";

import { PluginOptions } from "../../types/package.types";
import { info } from "../../utils/log.utils";

export const parseTypescriptToJson = async (
packageDocsPath: string,
docsJsonPath: string,
entryPoints: string[],
tsconfig: string,
pluginOptions: PluginOptions,
) => {
// 1. Prepare typedoc application to render
const app = new TypeDoc.Application();
try {
// 1. Parser options to bootstrap project
const app = await Application.bootstrapWithPlugins({
excludeExternals: true,
excludeInternal: true,
excludePrivate: true,
excludeProtected: true,
exclude: [
"node_modules",
"tests",
"__tests__",
"**/*.spec.ts",
"**/*.test.ts",
"**/*.tests.ts",
],
logLevel: "Error",
entryPointStrategy: "expand",
...pluginOptions.typeDocOptions,
plugin: ["typedoc-plugin-markdown", ...(pluginOptions.typeDocOptions?.plugin || [])],
tsconfig,
entryPoints,
});

// 2. Prepare parser readers
app.options.addReader(new TypeDoc.TSConfigReader());
app.options.addReader(new TypeDoc.TypeDocReader());
// 2. Prepare parser readers
app.options.addReader(new TSConfigReader());
app.options.addReader(new TypeDocReader());

// 3. Parser options to bootstrap project
app.bootstrap({
excludeExternals: true,
excludeInternal: true,
excludePrivate: true,
excludeProtected: true,
exclude: ["node_modules", "tests", "__tests__", "*.spec.ts", "*.test.ts"],
logLevel: "Error",
entryPointStrategy: "expand",
...pluginOptions.typeDocOptions,
plugin: ["typedoc-plugin-markdown", ...(pluginOptions.typeDocOptions?.plugin || [])],
tsconfig,
entryPoints,
});
// 3. Parse project
const project = await app.convert();

// 4. Generate json output
const project = app.convert();
if (project) {
await app.generateJson(project, packageDocsPath);
} else {
throw new Error(`Cannot generate docs for dir: ${packageDocsPath}.`);
// 4. Generate json output
if (pluginOptions.watch) {
app.convertAndWatch(async (watchProject) => {
info("Watching for changes...");
await app.generateJson(watchProject, docsJsonPath);
});
} else if (project) {
await app.generateJson(project, docsJsonPath);
} else {
throw new Error(`Cannot generate docs for dir: ${docsJsonPath}.`);
}
} catch (err) {
console.error(err);
}
};
Loading

0 comments on commit e14aea5

Please sign in to comment.