feat(docs): Add indicator for keyword-only arguments, add link to met…

…hod sources (#134) The docs were not showing which method arguments are positional and which are keyword-only. This adjusts the docs generation so that there is a `*` in the argument list before the first keyword-only argument, and also that there is a `keyword-only` tag next to those arguments. And while I was messing with it I adjusted it so that the methods also include a link to their source code. This might be pretty hard to review code-wise, because it's mostly just package patches, so I think just check if you think the result is OK, or if it should be adjusted. For the future, I vote to fork `docusaurus-plugin-typedoc-api` and use the fork here, so that the changes we make to it are more reviewable. Once approved, I will do it in the SDK as well. <img width="1358" alt="Screenshot 2023-07-25 at 19 37 15" src="https://github.com/apify/apify-client-python/assets/2934111/e7b5fb8b-fe38-45e2-8119-27c4014ad94d">
apify · Jul 26, 2023 · 0a679d6 · 0a679d6
1 parent 244d07d
commit 0a679d6
Show file tree

Hide file tree

Showing 3 changed files with 178 additions and 66 deletions.
diff --git 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
@@ -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
-+				<span>{sig.modifiers ? sig.modifiers.join(' ') : ''}<b>sig.name</b></span>
- 			) : sig.kindString === 'Constructor signature' ? (
- 				<>
- 					{sig.flags?.isAbstract && <span className="tsd-signature-symbol">abstract </span>}
-@@ -35,13 +35,6 @@ export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatur
- 					<span>
- 						{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
- 						{param.name}
--
--						<span className="tsd-signature-symbol">
--							{(param.flags?.isOptional || 'defaultValue' in param) && '?'}
--							{': '}
--						</span>
--
--						<Type type={param.type} />
- 					</span>
- 				</React.Fragment>
- 			))}
diff --git 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),
                 }];
             }