diff --git a/pyproject.toml b/pyproject.toml index 8bca97cf..79c9e6af 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,7 +46,7 @@ dev = [ "mypy ~= 1.3.0", "pep8-naming ~= 0.13.3", "pre-commit ~= 3.3.2", - "pydoc-markdown ~= 4.6.4", + "pydoc-markdown ~= 4.8.2", "pytest ~= 7.3.1", "pytest-asyncio ~= 0.21.0", "pytest-only ~= 2.0.0", diff --git a/website/patches/docusaurus-plugin-typedoc-api+2.5.1.patch b/website/patches/docusaurus-plugin-typedoc-api+2.5.1.patch index 3f2015d1..51c57cc4 100644 --- a/website/patches/docusaurus-plugin-typedoc-api+2.5.1.patch +++ b/website/patches/docusaurus-plugin-typedoc-api+2.5.1.patch @@ -1,55 +1,183 @@ +diff --git a/node_modules/docusaurus-plugin-typedoc-api/assets/styles-8ad572ec.css b/node_modules/docusaurus-plugin-typedoc-api/assets/styles-8ad572ec.css +index f3be380..30a4dde 100644 +--- a/node_modules/docusaurus-plugin-typedoc-api/assets/styles-8ad572ec.css ++++ b/node_modules/docusaurus-plugin-typedoc-api/assets/styles-8ad572ec.css +@@ -187,8 +187,20 @@ html[data-theme='light'] .tsd-panel-content { + opacity: 0.35; + } + ++.tsd-signature-default-value { ++ margin-left: 0.2rem; ++} ++ + /* FLAGS */ + ++.tsd-flag-group-left { ++ margin-right: 0.5rem; ++} ++ ++.tsd-flag-group-right { ++ margin-left: 0.5rem; ++} ++ + .tsd-flag { + display: inline-block; + padding: 3px 6px; +@@ -199,11 +211,14 @@ html[data-theme='light'] .tsd-panel-content { + font-size: var(--tsd-font-small); + font-weight: normal; + margin-top: -1px; +- margin-right: 0.5rem; + opacity: 0.65; + vertical-align: middle; + } + ++.tsd-flag:not(:first-child) { ++ margin-left: 0.25rem; ++} ++ + /* MODIFIERS */ + + .badge-group { +diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/components/DefaultValue.js b/node_modules/docusaurus-plugin-typedoc-api/lib/components/DefaultValue.js +index 62aab85..4737b3b 100644 +--- a/node_modules/docusaurus-plugin-typedoc-api/lib/components/DefaultValue.js ++++ b/node_modules/docusaurus-plugin-typedoc-api/lib/components/DefaultValue.js +@@ -50,7 +50,7 @@ function DefaultValue({ + } + + return /*#__PURE__*/React__default.default.createElement("span", { +- className: "tsd-signature-symbol" ++ className: "tsd-signature-symbol tsd-signature-default-value" + }, ' = ', value && /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, typeof value === 'string' ? value : /*#__PURE__*/React__default.default.createElement(Type.Type, { + type: value + })), !value && defaultTag && /*#__PURE__*/React__default.default.createElement(Type.Type, { +diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/components/Flags.js b/node_modules/docusaurus-plugin-typedoc-api/lib/components/Flags.js +index cd71c6b..7d470c0 100644 +--- a/node_modules/docusaurus-plugin-typedoc-api/lib/components/Flags.js ++++ b/node_modules/docusaurus-plugin-typedoc-api/lib/components/Flags.js +@@ -18,13 +18,17 @@ function removePrefix(value) { + } + + function Flags({ +- flags ++ flags, ++ position + }) { + if (!flags) { + return null; + } + +- return /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, Object.keys(flags).map(removePrefix).map(flag => /*#__PURE__*/React__default.default.createElement("span", { ++ const resolvedPosition = position ?? 'left'; ++ return /*#__PURE__*/React__default.default.createElement("span", { ++ className: `tsd-flag-group tsd-flag-group-${resolvedPosition}` ++ }, Object.keys(flags).map(removePrefix).map(flag => /*#__PURE__*/React__default.default.createElement("span", { + key: flag, + className: `tsd-flag tsd-flag-${flag}` + }, flag))); +diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureBody.js b/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureBody.js +index b557f56..f989c10 100644 +--- a/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureBody.js ++++ b/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureBody.js +@@ -83,9 +83,7 @@ function MemberSignatureBody({ + className: "tsd-parameters" + }, sig.parameters?.map(param => /*#__PURE__*/React__default.default.createElement("li", { + key: param.id +- }, /*#__PURE__*/React__default.default.createElement("h5", null, /*#__PURE__*/React__default.default.createElement(Flags.Flags, { +- flags: param.flags +- }), param.flags?.isRest && /*#__PURE__*/React__default.default.createElement("span", { ++ }, /*#__PURE__*/React__default.default.createElement("h5", null, param.flags?.isRest && /*#__PURE__*/React__default.default.createElement("span", { + className: "tsd-signature-symbol" + }, "..."), `${param.name}: `, /*#__PURE__*/React__default.default.createElement(Type.Type, { + type: param.type +@@ -93,6 +91,9 @@ function MemberSignatureBody({ + comment: param.comment, + type: param.type, + value: param.defaultValue ++ }), /*#__PURE__*/React__default.default.createElement(Flags.Flags, { ++ flags: param.flags, ++ position: "right" + })), /*#__PURE__*/React__default.default.createElement(Comment.Comment, { + comment: param.comment + }))))), showReturn && /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, /*#__PURE__*/React__default.default.createElement("h4", { diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureTitle.js b/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureTitle.js -index 0a36b74..4a2b7fb 100644 +index 0a36b74..e5bc1a9 100644 --- a/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureTitle.js +++ b/node_modules/docusaurus-plugin-typedoc-api/lib/components/MemberSignatureTitle.js -@@ -23,7 +23,9 @@ function MemberSignatureTitle({ +@@ -23,7 +23,21 @@ function MemberSignatureTitle({ hideName, sig }) { - return /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, !hideName && sig.name !== '__type' ? sig.name : sig.kindString === 'Constructor signature' ? /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, sig.flags?.isAbstract && /*#__PURE__*/React__default.default.createElement("span", { -+ return /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, !hideName && sig.name !== '__type' ? -+ React__default.default.createElement("span", null, (sig.modifiers ? `${sig.modifiers.join(' ')} ` : ''), React__default.default.createElement("b", null, sig.name)) -+ : sig.kindString === 'Constructor signature' ? /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, sig.flags?.isAbstract && /*#__PURE__*/React__default.default.createElement("span", { ++ const parametersCopy = sig.parameters?.slice() ?? []; // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access ++ ++ const firstKeywordOnlyIndex = parametersCopy.findIndex(param => param.flags?.['keyword-only']); // add a special modifier before the first keyword-only parameter ++ ++ if (firstKeywordOnlyIndex >= 0) { ++ parametersCopy.splice(firstKeywordOnlyIndex, 0, { ++ id: 999_999, ++ name: '*', ++ kind: 32_768, ++ flags: {}, ++ permalink: '' ++ }); ++ } ++ ++ return /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, !hideName && sig.name !== '__type' ? /*#__PURE__*/React__default.default.createElement("span", null, sig.modifiers ? `${sig.modifiers.join(' ')} ` : '', /*#__PURE__*/React__default.default.createElement("b", null, sig.name)) : sig.kindString === 'Constructor signature' ? /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, sig.flags?.isAbstract && /*#__PURE__*/React__default.default.createElement("span", { className: "tsd-signature-symbol" }, "abstract "), /*#__PURE__*/React__default.default.createElement("span", { className: "tsd-signature-symbol" -@@ -39,8 +41,6 @@ function MemberSignatureTitle({ +@@ -31,17 +45,13 @@ function MemberSignatureTitle({ + params: sig.typeParameter + }), /*#__PURE__*/React__default.default.createElement("span", { + className: "tsd-signature-symbol" +- }, "("), sig.parameters?.map((param, index) => /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, { ++ }, "("), parametersCopy.map((param, index) => /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, { + key: param.id + }, index > 0 && /*#__PURE__*/React__default.default.createElement("span", { className: "tsd-signature-symbol" - }, "..."), param.name, /*#__PURE__*/React__default.default.createElement("span", { + }, ", "), /*#__PURE__*/React__default.default.createElement("span", null, param.flags?.isRest && /*#__PURE__*/React__default.default.createElement("span", { className: "tsd-signature-symbol" +- }, "..."), param.name, /*#__PURE__*/React__default.default.createElement("span", { +- className: "tsd-signature-symbol" - }, (param.flags?.isOptional || 'defaultValue' in param) && '?', ': '), /*#__PURE__*/React__default.default.createElement(Type.Type, { - type: param.type - })))), /*#__PURE__*/React__default.default.createElement("span", { +- })))), /*#__PURE__*/React__default.default.createElement("span", { ++ }, "..."), param.name))), /*#__PURE__*/React__default.default.createElement("span", { className: "tsd-signature-symbol" }, ")"), sig.type && /*#__PURE__*/React__default.default.createElement(React__default.default.Fragment, null, /*#__PURE__*/React__default.default.createElement("span", { + className: "tsd-signature-symbol" diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/index.js b/node_modules/docusaurus-plugin-typedoc-api/lib/index.js -index 8c9d33a..0f9f3cc 100644 +index 8c9d33a..631eb3c 100644 --- a/node_modules/docusaurus-plugin-typedoc-api/lib/index.js +++ b/node_modules/docusaurus-plugin-typedoc-api/lib/index.js -@@ -55,7 +55,8 @@ const DEFAULT_OPTIONS = { - routeBasePath: 'api', - tsconfigName: 'tsconfig.json', - typedocOptions: {}, -- versions: {} -+ versions: {}, -+ pathToTypedocJSON: false, - }; - - async function importFile(file) { -@@ -152,7 +153,15 @@ function typedocApiPlugin(context, pluginOptions) { +@@ -46,6 +46,7 @@ const DEFAULT_OPTIONS = { + onlyIncludeVersions: [], + packageJsonName: 'package.json', + packages: [], ++ pathToTypedocJSON: '', + projectRoot: '.', + sortPackages: (a, d) => a.packageName.localeCompare(d.packageName), + sortSidebar: (a, d) => a.localeCompare(d), +@@ -152,7 +153,19 @@ function typedocApiPlugin(context, pluginOptions) { if (metadata.versionName === server.CURRENT_VERSION_NAME) { const outFile = path__default.default.join(context.generatedFilesDir, `api-typedoc-${pluginId}.json`); - await data.generateJson(projectRoot, entryPoints, outFile, options); ++ + if (!options.pathToTypedocJSON) { -+ await data.generateJson(projectRoot, entryPoints, outFile, options) -+ } -+ else { -+ if (!fs.existsSync(context.generatedFilesDir)){ -+ fs.mkdirSync(context.generatedFilesDir, { recursive: true }); ++ await data.generateJson(projectRoot, entryPoints, outFile, options); ++ } else { ++ if (!fs__default.default.existsSync(context.generatedFilesDir)) { ++ fs__default.default.mkdirSync(context.generatedFilesDir, { ++ recursive: true ++ }); + } -+ fs.copyFileSync(options.pathToTypedocJSON, outFile); -+ } ++ ++ fs__default.default.copyFileSync(options.pathToTypedocJSON, outFile); ++ } ++ packages = data.flattenAndGroupPackages(packageConfigs, await importFile(outFile), metadata.versionPath, options); // Versioned data is stored in the file system } else { const outDir = path__default.default.join(versionsDocsDir, `version-${metadata.versionName}`); @@ -66,38 +194,3 @@ index 8878837..e9d2822 100644 function getLastItemInGroup(index) { const length = sortedGroups[index]?.children?.length; -diff --git a/node_modules/docusaurus-plugin-typedoc-api/src/components/MemberSignatureTitle.tsx b/node_modules/docusaurus-plugin-typedoc-api/src/components/MemberSignatureTitle.tsx -index cfa5765..a60ca02 100644 ---- a/node_modules/docusaurus-plugin-typedoc-api/src/components/MemberSignatureTitle.tsx -+++ b/node_modules/docusaurus-plugin-typedoc-api/src/components/MemberSignatureTitle.tsx -@@ -9,14 +9,14 @@ import { TypeParametersGeneric } from './TypeParametersGeneric'; - export interface MemberSignatureTitleProps { - useArrow?: boolean; - hideName?: boolean; -- sig: JSONOutput.SignatureReflection; -+ sig: JSONOutput.SignatureReflection & { modifiers?: string[] }; - } - - export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatureTitleProps) { - return ( - <> - {!hideName && sig.name !== '__type' ? ( -- sig.name -+ {sig.modifiers ? sig.modifiers.join(' ') : ''}sig.name - ) : sig.kindString === 'Constructor signature' ? ( - <> - {sig.flags?.isAbstract && abstract } -@@ -35,13 +35,6 @@ export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatur - - {param.flags?.isRest && ...} - {param.name} -- -- -- {(param.flags?.isOptional || 'defaultValue' in param) && '?'} -- {': '} -- -- -- - - - ))} diff --git a/website/transformDocs.js b/website/transformDocs.js index 1f86b53a..5a3dd77c 100644 --- a/website/transformDocs.js +++ b/website/transformDocs.js @@ -3,6 +3,9 @@ const fs = require('fs'); const path = require('path'); +const REPO_BASE_URL = 'https://github.com/apify/apify-client-python'; +const DEFAULT_BRANCH = 'master'; + const acc = { 'id': 0, 'name': 'apify-client', @@ -17,7 +20,7 @@ const acc = { 'fileName': 'src/index.ts', 'line': 1, 'character': 0, - 'url': 'https://github.com/apify/apify-client-python/blob/123456/src/dummy.py' + 'url': `${REPO_BASE_URL}/blob/123456/src/dummy.py`, } ] }; @@ -98,9 +101,14 @@ function isCustomClass(s) { } function inferType(x) { - return !isCustomClass(stripOptional(x) ?? '') ? { + const typeWithoutOptional = stripOptional(x); + if (!typeWithoutOptional) { + return undefined; + } + + return !isCustomClass(stripOptional(x)) ? { type: 'intrinsic', - name: stripOptional(x) ?? 'void', + name: stripOptional(x), } : { type: 'reference', name: stripOptional(x), @@ -156,6 +164,9 @@ function traverse(o, parent) { } if(x.type in kinds && !isHidden(x)) { + const filePathInRepo = path.relative(path.join(__dirname, '..'), x.location.filename); + const memberGitHubUrl = `${REPO_BASE_URL}/blob/${DEFAULT_BRANCH}/${filePathInRepo}#L${x.location.lineno}`; + let newObj = { id: oid++, name: x.name, @@ -170,6 +181,12 @@ function traverse(o, parent) { type, children: [], groups: [], + sources: [{ + filename: filePathInRepo, + line: x.location.lineno, + character: 1, + url: memberGitHubUrl, + }], }; if(newObj.kindString === 'Method') { @@ -197,6 +214,7 @@ function traverse(o, parent) { kindString: 'Parameter', flags: { isOptional: p.datatype?.includes('Optional') ? 'true' : undefined, + 'keyword-only': p.type === 'KEYWORD_ONLY' ? 'true' : undefined, }, type: inferType(p.datatype), comment: parameters[p.name] ? { @@ -205,6 +223,7 @@ function traverse(o, parent) { text: parameters[p.name] }] } : undefined, + defaultValue: p.default_value, })).filter(x => x), }]; }