@alauda/doom 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -14,7 +14,7 @@ const getCommonConfig = (config) => {
14
14
  return {
15
15
  lang: 'en',
16
16
  route: {
17
- exclude: ['shared/**/*', 'doom.config.*'],
17
+ exclude: ['shared/**/*', 'doom.config.*', '**/assets/**/*'],
18
18
  },
19
19
  markdown: {
20
20
  checkDeadLinks: true,
@@ -5,7 +5,7 @@ import { glob } from 'tinyglobby';
5
5
  import { resolveStaticConfig } from '../../utils/index.js';
6
6
  const crdsMap = {};
7
7
  const openapisMap = {};
8
- let allReferences;
8
+ const shared = {};
9
9
  export const apiPlugin = () => {
10
10
  return {
11
11
  name: 'doom-api',
@@ -14,7 +14,7 @@ export const apiPlugin = () => {
14
14
  if (!config.api) {
15
15
  return;
16
16
  }
17
- const { crds, openapis, references } = config.api;
17
+ const { crds, openapis, references, pathPrefix } = config.api;
18
18
  if (crds) {
19
19
  for (const file of await glob(crds, {
20
20
  cwd: config.root,
@@ -39,12 +39,14 @@ export const apiPlugin = () => {
39
39
  openapisMap[file] = doc;
40
40
  }
41
41
  }
42
- allReferences = references;
42
+ shared.references = references;
43
+ shared.pathPrefix = pathPrefix;
43
44
  },
44
45
  extendPageData(pageData) {
45
46
  pageData.crdsMap = crdsMap;
46
47
  pageData.openapisMap = openapisMap;
47
- pageData.references = allReferences;
48
+ pageData.references = shared.references;
49
+ pageData.pathPrefix = shared.pathPrefix;
48
50
  },
49
51
  };
50
52
  };
@@ -58,7 +58,7 @@ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, exten
58
58
  });
59
59
  sideMeta = (await Promise.all(subItems.map(async (item) => {
60
60
  // Fix https://github.com/web-infra-dev/rspress/issues/346
61
- if (item === '_meta.json') {
61
+ if (item === '_meta.json' || item === 'assets') {
62
62
  return null;
63
63
  }
64
64
  const stat = await fs.stat(path.join(workDir, item));
@@ -3,7 +3,14 @@
3
3
  */
4
4
  import { OpenAPIV3_1 } from 'openapi-types';
5
5
  export interface K8sCrdProps {
6
+ /**
7
+ * The `metadata.name` of the CustomResourceDefinition
8
+ */
6
9
  name: string;
10
+ /**
11
+ * The specific path to the CRD, otherwise the first matched will be used.
12
+ */
13
+ crdPath?: string;
7
14
  }
8
15
  export declare const K8sCrdSchemaPart: ({ name, parent, schema: property, openAll, }: {
9
16
  name: string;
@@ -15,5 +22,5 @@ export declare const K8sCrdSchema: ({ schema, version, }: {
15
22
  schema: OpenAPIV3_1.SchemaObject;
16
23
  version: string;
17
24
  }) => import("react/jsx-runtime").JSX.Element;
18
- export declare const K8sCrd: ({ name }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element | null;
25
+ export declare const K8sCrd: ({ name, crdPath }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element | null;
19
26
  export default K8sCrd;
@@ -41,6 +41,7 @@ export const K8sCrdSchemaPart = ({ name, parent, schema: property, openAll, }) =
41
41
  return (_jsx(_Fragment, { children: _jsxs(Directive, { type: "details", title: _jsxs(_Fragment, { children: [name, type && _jsx(X.code, { children: type }), required && _jsx(Badge, { children: "required" })] }), open: open, onToggle: onToggle, children: [_jsx(Markdown, { children: schema.description }), props &&
42
42
  Object.entries(props).map(([name, subSchema]) => (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name)))] }) }));
43
43
  };
44
+ const SKIPPED_PROPERTIES = ['apiVersion', 'kind', 'metadata'];
44
45
  export const K8sCrdSchema = ({ schema, version, }) => {
45
46
  const { description, properties } = schema;
46
47
  const t = useTranslation();
@@ -51,11 +52,16 @@ export const K8sCrdSchema = ({ schema, version, }) => {
51
52
  const collapseAll = useCallback(() => {
52
53
  setOpenAll(false);
53
54
  }, []);
54
- return (_jsxs(_Fragment, { children: [_jsx(Markdown, { children: description }), _jsxs("div", { className: "flex items-center", children: [_jsxs("span", { children: [_jsx(X.code, { children: version }), _jsx(Badge, { children: "version" })] }), properties != null && (_jsxs("div", { className: "ml-auto", children: [_jsx(Button, { className: "doom-btn", type: "button", text: _jsxs("span", { onClick: collapseAll, children: ["- ", t('collapse_all')] }), size: "medium", theme: "alt" }), _jsx(Button, { className: "doom-btn ml-2", type: "button", text: _jsxs("span", { onClick: expandAll, children: ["+ ", t('expand_all')] }), size: "medium", theme: "alt" })] }))] }), properties == null ? (_jsx(Directive, { type: "warning", children: t('crd_no_schema') })) : (_jsx("div", { className: "doom-collapse-group", children: Object.entries(properties).map(([name, subSchema]) => (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name))) }))] }));
55
+ return (_jsxs(_Fragment, { children: [_jsx(Markdown, { children: description }), _jsxs("div", { className: "flex items-center", children: [_jsxs("span", { children: [_jsx(X.code, { children: version }), _jsx(Badge, { children: "version" })] }), properties != null && (_jsxs("div", { className: "ml-auto", children: [_jsx(Button, { className: "doom-btn", type: "button", text: _jsxs("span", { onClick: collapseAll, children: ["- ", t('collapse_all')] }), size: "medium", theme: "alt" }), _jsx(Button, { className: "doom-btn ml-2", type: "button", text: _jsxs("span", { onClick: expandAll, children: ["+ ", t('expand_all')] }), size: "medium", theme: "alt" })] }))] }), properties == null ? (_jsx(Directive, { type: "warning", children: t('crd_no_schema') })) : (_jsx("div", { className: "doom-collapse-group", children: Object.entries(properties).map(([name, subSchema]) => SKIPPED_PROPERTIES.includes(name) || (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name))) }))] }));
55
56
  };
56
- export const K8sCrd = ({ name }) => {
57
+ export const K8sCrd = ({ name, crdPath }) => {
57
58
  const { page } = usePageData();
58
- const crd = useMemo(() => Object.values(page.crdsMap || {}).find((crd) => crd.metadata.name === name), [page]);
59
+ const [, crd] = useMemo(() => Object.entries(page.crdsMap || {}).find(([pathname, crd]) => {
60
+ if (crdPath && pathname !== crdPath) {
61
+ return false;
62
+ }
63
+ return crd.metadata.name === name;
64
+ }) || [], [page]);
59
65
  if (!crd) {
60
66
  console.error(`No CustomResourceDefinition found for ${name}`);
61
67
  return null;
@@ -1,6 +1,17 @@
1
1
  import { OpenAPIV3_1 } from 'openapi-types';
2
2
  export interface OpenAPIPathProps {
3
+ /**
4
+ * The path under the OpenAPI schema `paths` definition.
5
+ */
3
6
  path: string;
7
+ /**
8
+ * The specific path to the OpenAPI schema, otherwise the first matched will be used.
9
+ */
10
+ openapiPath?: string;
11
+ /**
12
+ * If you have a gateway which adds common path prefix, can be used to override global config level `pathPrefix`.
13
+ */
14
+ pathPrefix?: string;
4
15
  }
5
16
  export declare const OpenAPIParameters: ({ parameters, openapi, }: {
6
17
  parameters: Array<OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
@@ -10,5 +21,5 @@ export declare const OpenAPIResponses: ({ responses, openapi, }: {
10
21
  responses: OpenAPIV3_1.ResponsesObject;
11
22
  openapi: OpenAPIV3_1.Document;
12
23
  }) => import("react/jsx-runtime").JSX.Element;
13
- export declare const OpenAPIPath: ({ path }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
24
+ export declare const OpenAPIPath: ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
14
25
  export default OpenAPIPath;
@@ -1,6 +1,6 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
2
  import { usePageData } from '@rspress/core/runtime';
3
- import { getCustomMDXComponent } from '@rspress/core/theme';
3
+ import { Badge, getCustomMDXComponent } from '@rspress/core/theme';
4
4
  import BananaSlug from 'github-slugger';
5
5
  import { OpenAPIV3 } from 'openapi-types';
6
6
  import { useMemo } from 'react';
@@ -24,7 +24,7 @@ export const OpenAPIParameters = ({ parameters, openapi, }) => {
24
24
  else if (type) {
25
25
  typeNode = _jsx(RefLink, { "$ref": type.$ref });
26
26
  }
27
- return (_jsxs(X.li, { children: [_jsx(X.code, { children: paramObj.name }), "(", _jsxs("em", { children: ["in ", paramObj.in] }), "):", ' ', typeNode, ", ", paramObj.required ? 'required' : 'optional', _jsx(Markdown, { children: paramObj.description })] }, index));
27
+ return (_jsxs(X.li, { children: [_jsx(X.code, { children: paramObj.name }), "(", _jsxs("em", { children: ["in ", paramObj.in] }), "):", ' ', typeNode, paramObj.required && _jsx(Badge, { children: "required" }), _jsx(Markdown, { children: paramObj.description })] }, index));
28
28
  }) }));
29
29
  };
30
30
  export const OpenAPIResponses = ({ responses, openapi, }) => {
@@ -72,16 +72,21 @@ const getRefsForPath = (openapi, path, knownRefs) => {
72
72
  }
73
73
  return Array.from(refs);
74
74
  };
75
- export const OpenAPIPath = ({ path }) => {
75
+ export const OpenAPIPath = ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }) => {
76
76
  const { page } = usePageData();
77
+ const pathPrefix = pathPrefix_ ?? (page.pathPrefix || '');
77
78
  const slugger = useMemo(() => new BananaSlug(), []);
78
- const [pathItem, openapi, refs] = useMemo(() => {
79
- for (const openapi of Object.values(page.openapisMap || {})) {
79
+ const [pathItem, openapi, openapiPath, refs] = useMemo(() => {
80
+ for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
81
+ if (openapiPath_ && pathname !== openapiPath_) {
82
+ continue;
83
+ }
80
84
  const pathItem = openapi.paths?.[path];
81
85
  if (pathItem) {
82
86
  return [
83
87
  pathItem,
84
88
  openapi,
89
+ pathname,
85
90
  getRefsForPath(openapi, path, omitRoutePathRefs({
86
91
  ...page.references,
87
92
  ...DEFAULT_COMMON_REFS,
@@ -95,16 +100,21 @@ export const OpenAPIPath = ({ path }) => {
95
100
  console.error(`No OpenAPI path definition found for ${path}`);
96
101
  return null;
97
102
  }
98
- return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 2, children: path }), pathItem.parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 3, children: "Common Parameters" }), _jsx(OpenAPIParameters, { parameters: pathItem.parameters, openapi: openapi })] })), Object.values(OpenAPIV3.HttpMethods).map((method) => {
103
+ return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 2, children: [pathPrefix, path] }), pathItem.parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 3, children: "Common Parameters" }), _jsx(OpenAPIParameters, { parameters: pathItem.parameters, openapi: openapi })] })), Object.values(OpenAPIV3.HttpMethods).map((method) => {
99
104
  if (!pathItem[method]) {
100
105
  return null;
101
106
  }
102
107
  const { description, parameters, requestBody, responses, summary } = pathItem[method];
103
- return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 3, children: [_jsx(X.code, { children: method }), summary] }), _jsx(Markdown, { children: description }), parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Parameters" }), _jsx(OpenAPIParameters, { parameters: parameters, openapi: openapi })] })), requestBody && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Request Body" }), _jsx(RefLink, { "$ref": '$ref' in requestBody
104
- ? requestBody.$ref
105
- : requestBody.content['application/json'].schema?.$ref })] })), responses && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Response" }), _jsx(OpenAPIResponses, { responses: responses, openapi: openapi })] }))] }));
108
+ const requestBodyRef = requestBody &&
109
+ ('$ref' in requestBody
110
+ ? requestBody.$ref
111
+ : requestBody.content['application/json'].schema?.$ref);
112
+ const requestBodySchema = requestBodyRef
113
+ ? resolveRef(openapi, requestBodyRef)
114
+ : undefined;
115
+ return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 3, children: [_jsx(X.code, { children: method }), summary] }), _jsx(Markdown, { children: description }), parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Parameters" }), _jsx(OpenAPIParameters, { parameters: parameters, openapi: openapi })] })), requestBodySchema && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Request Body" }), _jsxs(X.p, { children: [_jsx(RefLink, { "$ref": requestBodyRef }), requestBodySchema.required && _jsx(Badge, { children: "required" })] })] })), responses && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Response" }), _jsx(OpenAPIResponses, { responses: responses, openapi: openapi })] }))] }));
106
116
  }), refs?.map((ref, index) => {
107
- return (_jsx(OpenAPIRef, { schema: ref, openapi: openapi, collectRefs: false }, index));
117
+ return (_jsx(OpenAPIRef, { schema: ref, openapiPath: openapiPath, collectRefs: false }, index));
108
118
  })] }));
109
119
  };
110
120
  export default OpenAPIPath;
@@ -1,12 +1,18 @@
1
1
  import { OpenAPIV3_1 } from 'openapi-types';
2
2
  export interface OpenAPIRefProps {
3
+ /**
4
+ * The schema name under the OpenAPI schema `definitions` (swagger 2.0) or `components/schemas` (openapi 3.x).
5
+ */
3
6
  schema: string;
4
- openapi?: OpenAPIV3_1.Document;
7
+ /**
8
+ * The specific path to the OpenAPI schema, otherwise the first matched will be used.
9
+ */
10
+ openapiPath?: string;
5
11
  collectRefs?: boolean;
6
12
  }
7
13
  export declare const OpenAPIProperties: ({ properties, openapi, }: {
8
14
  properties: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject>;
9
15
  openapi: OpenAPIV3_1.Document;
10
16
  }) => import("react/jsx-runtime").JSX.Element;
11
- export declare const OpenAPIRef: ({ schema, openapi: openapi_, collectRefs, }: OpenAPIRefProps) => import("react/jsx-runtime").JSX.Element | null;
17
+ export declare const OpenAPIRef: ({ schema, openapiPath: openapiPath_, collectRefs, }: OpenAPIRefProps) => import("react/jsx-runtime").JSX.Element | null;
12
18
  export default OpenAPIRef;
@@ -4,8 +4,8 @@ import { getCustomMDXComponent } from '@rspress/theme-default';
4
4
  import { useMemo } from 'react';
5
5
  import { DEFAULT_COMMON_REFS, modelName, omitRoutePathRefs, resolveRef, } from '../utils.js';
6
6
  import { HeadingTitle } from './_HeadingTitle.js';
7
- import { RefLink } from './_RefLink.js';
8
7
  import { Markdown } from './_Markdown.js';
8
+ import { RefLink } from './_RefLink.js';
9
9
  const X = getCustomMDXComponent();
10
10
  export const OpenAPIProperties = ({ properties, openapi, }) => {
11
11
  return (_jsx(X.ul, { children: Object.entries(properties).map(([name, prop], index) => {
@@ -65,20 +65,16 @@ const getRefsForSchema = (openapi, schema, knownRefs) => {
65
65
  collectRefs(refSchema);
66
66
  return Array.from(refs);
67
67
  };
68
- export const OpenAPIRef = ({ schema, openapi: openapi_, collectRefs = true, }) => {
68
+ export const OpenAPIRef = ({ schema, openapiPath: openapiPath_, collectRefs = true, }) => {
69
69
  const { page } = usePageData();
70
- const [schemaItem, openapi] = useMemo(() => {
71
- if (openapi_) {
72
- return [
73
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments -- no sure to understand
74
- resolveRef(openapi_, schema),
75
- openapi_,
76
- ];
77
- }
78
- for (const openapi of Object.values(page.openapisMap || {})) {
70
+ const [schemaItem, openapi, openapiPath] = useMemo(() => {
71
+ for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
72
+ if (openapiPath_ && pathname !== openapiPath_) {
73
+ continue;
74
+ }
79
75
  const schemaItem = openapi.components?.schemas?.[schema];
80
76
  if (schemaItem) {
81
- return [schemaItem, openapi];
77
+ return [schemaItem, openapi, pathname];
82
78
  }
83
79
  }
84
80
  return [];
@@ -95,6 +91,6 @@ export const OpenAPIRef = ({ schema, openapi: openapi_, collectRefs = true, }) =
95
91
  }, page.routePath));
96
92
  }
97
93
  }, [collectRefs, openapi, page.routePath, schema]);
98
- return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema, openapi: openapi, collectRefs: false }, index)))] }));
94
+ return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema, openapiPath: openapiPath, collectRefs: false }, index)))] }));
99
95
  };
100
96
  export default OpenAPIRef;
@@ -18,7 +18,7 @@ export function Overview(props) {
18
18
  if ('link' in traverseItem && traverseItem.link) {
19
19
  return traverseItem.link;
20
20
  }
21
- if ('items' in traverseItem) {
21
+ if ('items' in traverseItem && traverseItem.items.length) {
22
22
  return getChildLink(traverseItem.items[0]);
23
23
  }
24
24
  return '';
@@ -5,6 +5,7 @@ export interface ExtendedPage {
5
5
  crdsMap?: Record<string, CustomResourceDefinition>;
6
6
  openapisMap?: Record<string, OpenAPIV3_1.Document>;
7
7
  references?: Record<string, string>;
8
+ pathPrefix?: string;
8
9
  }
9
10
  export interface ExtendedPageData extends PageData {
10
11
  page: PageData['page'] & ExtendedPage;
@@ -4,5 +4,6 @@ export interface DoomConfig extends UserConfig {
4
4
  crds?: string[];
5
5
  openapis?: string[];
6
6
  references?: Record<string, string>;
7
+ pathPrefix?: string;
7
8
  };
8
9
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -28,6 +28,7 @@
28
28
  "clean": "tsc -b src --clean",
29
29
  "dev": "yarn swc-node --watch-path src/cli --watch-path src/plugins src/cli/index.ts",
30
30
  "doom": "yarn swc-node src/cli/index.ts",
31
+ "fixture": "yarn doom fixture-docs",
31
32
  "lint": "run-p 'lint:*'",
32
33
  "lint:es": "eslint .",
33
34
  "lint:tsc": "tsc -b --noEmit",