From afe1c97522992974a0c5c42247b8a0f83d0564b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= Date: Thu, 31 Oct 2024 17:09:43 +0100 Subject: [PATCH 1/2] feat: add Python-specific type helpers (`Unpack`, `NotRequired` etc.) --- packages/plugin/package.json | 4 +- .../src/components/MemberSignatureBody.tsx | 47 ++++++++++++++++++- packages/plugin/src/components/Type.tsx | 19 +++++++- 3 files changed, 64 insertions(+), 6 deletions(-) diff --git a/packages/plugin/package.json b/packages/plugin/package.json index 4a916af..10253e0 100644 --- a/packages/plugin/package.json +++ b/packages/plugin/package.json @@ -1,6 +1,6 @@ { "name": "@apify/docusaurus-plugin-typedoc-api", - "version": "4.2.6", + "version": "4.2.7", "description": "Docusaurus plugin that provides source code API documentation powered by TypeDoc. ", "keywords": [ "docusaurus", @@ -59,4 +59,4 @@ "react-dom": "^18.2.0", "typescript": "^5.3.3" } -} \ No newline at end of file +} diff --git a/packages/plugin/src/components/MemberSignatureBody.tsx b/packages/plugin/src/components/MemberSignatureBody.tsx index 75a52ad..8826be1 100644 --- a/packages/plugin/src/components/MemberSignatureBody.tsx +++ b/packages/plugin/src/components/MemberSignatureBody.tsx @@ -1,9 +1,12 @@ // https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.signature.body.hbs -import { Fragment } from 'react' +import { Fragment, useContext } from 'react' import type { JSONOutput, Models } from 'typedoc'; +import { GlobalData } from '@docusaurus/types'; +import { usePluginData } from '@docusaurus/useGlobalData'; import { useMinimalLayout } from '../hooks/useMinimalLayout'; import type { TSDSignatureReflection } from '../types'; +import { ApiDataContext } from './ApiDataContext'; import { Comment, hasComment } from './Comment'; import { CommentBadges, isCommentWithModifiers } from './CommentBadges'; import { DefaultValue } from './DefaultValue'; @@ -61,6 +64,46 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro const showParams = !minimal && sig.parameters && sig.parameters.length > 0; const showReturn = !minimal && sig.type; + const { reflections } = useContext(ApiDataContext); + const { isPython } = usePluginData('docusaurus-plugin-typedoc-api') as GlobalData; + + + if (isPython) { + // eslint-disable-next-line + sig.parameters = sig.parameters?.reduce((acc, param) => { + // @ts-expect-error Silence ts errors + switch (param.type?.name) { + case 'Unpack': + // @ts-expect-error Silence ts errors + // eslint-disable-next-line + acc.push(...reflections[param.type.typeArguments[0].target].children.map(x => ({...x, flags: {'keyword-only': true}}))); + break; + default: + acc.push(param); + break; + } + + return acc; + }, []); + + // eslint-disable-next-line + sig.parameters = sig.parameters?.reduce((acc, param) => { + // @ts-expect-error Silence ts errors + switch (param.type?.name) { + case 'NotRequired': + // @ts-expect-error Silence ts errors + // eslint-disable-next-line + acc.push({...param, type: param.type.typeArguments[0]}); + break; + default: + acc.push(param); + break; + } + + return acc; + }, []); + } + return ( <> {!hideSources && } @@ -127,7 +170,7 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro {param.type?.type === 'union' && ( (((param.type as unknown as Models.UnionType).types.filter( - (unionType) => unionType.type === 'reflection')) as Models.ReflectionType[]).map( + (unionType) => unionType.type === 'reflection'))).map( (unionReflectionType) => (
    {unionReflectionType.declaration?.children?.map((unionChild) => ( diff --git a/packages/plugin/src/components/Type.tsx b/packages/plugin/src/components/Type.tsx index 3128f8a..7a628c0 100644 --- a/packages/plugin/src/components/Type.tsx +++ b/packages/plugin/src/components/Type.tsx @@ -4,6 +4,8 @@ import { Fragment } from 'react'; import type { JSONOutput } from 'typedoc'; import Link from '@docusaurus/Link'; +import { GlobalData } from '@docusaurus/types'; +import { usePluginData } from '@docusaurus/useGlobalData'; import { useReflectionMap } from '../hooks/useReflectionMap'; import type { TSDDeclarationReflection } from '../types'; import { MemberSignatureTitle } from './MemberSignatureTitle'; @@ -40,6 +42,7 @@ export interface TypeProps { // eslint-disable-next-line complexity export function Type({ needsParens = false, type: base }: TypeProps) { const reflections = useReflectionMap(); + const { isPython } = usePluginData('docusaurus-plugin-typedoc-api') as GlobalData; if (!base) { return null; @@ -124,6 +127,10 @@ export function Type({ needsParens = false, type: base }: TypeProps) { case 'literal': { const type = base as JSONOutput.LiteralType; + if (isPython && type.value === null) { + return None; + } + return {String(type.value)}; } @@ -223,14 +230,22 @@ export function Type({ needsParens = false, type: base }: TypeProps) { )} {type.typeArguments && type.typeArguments.length > 0 && ( <> - < + + { + isPython ? '[' : '<' + } + {type.typeArguments.map((t, i) => ( {i > 0 && , } ))} - > + + { + isPython ? ']' : '>' + } + )} From 91f0c0eaa646f8ac4d96f7e2cca80d225103947e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= Date: Thu, 31 Oct 2024 17:19:51 +0100 Subject: [PATCH 2/2] fix: solve TS build problems --- packages/plugin/package.json | 2 +- packages/plugin/src/components/MemberSignatureBody.tsx | 6 +++--- packages/plugin/src/components/Type.tsx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/plugin/package.json b/packages/plugin/package.json index 10253e0..6d2edb8 100644 --- a/packages/plugin/package.json +++ b/packages/plugin/package.json @@ -59,4 +59,4 @@ "react-dom": "^18.2.0", "typescript": "^5.3.3" } -} +} \ No newline at end of file diff --git a/packages/plugin/src/components/MemberSignatureBody.tsx b/packages/plugin/src/components/MemberSignatureBody.tsx index 8826be1..863e2a1 100644 --- a/packages/plugin/src/components/MemberSignatureBody.tsx +++ b/packages/plugin/src/components/MemberSignatureBody.tsx @@ -2,7 +2,7 @@ import { Fragment, useContext } from 'react' import type { JSONOutput, Models } from 'typedoc'; -import { GlobalData } from '@docusaurus/types'; +import { type GlobalData } from '@docusaurus/types'; import { usePluginData } from '@docusaurus/useGlobalData'; import { useMinimalLayout } from '../hooks/useMinimalLayout'; import type { TSDSignatureReflection } from '../types'; @@ -169,8 +169,8 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro )} {param.type?.type === 'union' && ( - (((param.type as unknown as Models.UnionType).types.filter( - (unionType) => unionType.type === 'reflection'))).map( + ((param.type.types.filter( + (unionType) => unionType.type === 'reflection')) as unknown as Models.ReflectionType[]).map( (unionReflectionType) => (
      {unionReflectionType.declaration?.children?.map((unionChild) => ( diff --git a/packages/plugin/src/components/Type.tsx b/packages/plugin/src/components/Type.tsx index 7a628c0..0eb83f0 100644 --- a/packages/plugin/src/components/Type.tsx +++ b/packages/plugin/src/components/Type.tsx @@ -4,7 +4,7 @@ import { Fragment } from 'react'; import type { JSONOutput } from 'typedoc'; import Link from '@docusaurus/Link'; -import { GlobalData } from '@docusaurus/types'; +import { type GlobalData } from '@docusaurus/types'; import { usePluginData } from '@docusaurus/useGlobalData'; import { useReflectionMap } from '../hooks/useReflectionMap'; import type { TSDDeclarationReflection } from '../types';