feat: add the python docspec transformation tooling

.eslintrc.js

@@ -25,5 +25,9 @@ module.exports = {
 		'import/no-extraneous-dependencies': 'off',
 		'unicorn/prefer-ternary': 'off',
 		'unicorn/no-abusive-eslint-disable': 'off',
+		'no-plusplus': 'off',
+		// this is definitely code smell but we have a lot of it in the python transforming script
+		'no-param-reassign': 'off',
+		complexity: 'off',
 	},
 };

.github/workflows/release.yml

@@ -1,59 +1,61 @@
 name: Release @latest
 
 env:
-    YARN_IGNORE_NODE: 1
-    RETRY_TESTS: 1
+  YARN_IGNORE_NODE: 1
+  RETRY_TESTS: 1
 
 on:
-    workflow_dispatch:
+  workflow_dispatch:
 
 jobs:
-    release:
-        name: "Release"
-        if: (!contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, 'docs:'))
-        runs-on: ubuntu-latest
-
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v4
-              with:
-                  token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-                  fetch-depth: 0
-
-            - name: Use Node.js 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: 20
-
-            - name: Enable corepack
-              run: |
-                  corepack enable
-                  corepack prepare yarn@stable --activate
-
-            - name: Activate cache for Node.js 20
-              uses: actions/setup-node@v4
-              with:
-                  cache: 'yarn'
-
-            - name: Install Dependencies
-              run: yarn
-
-            - name: Build
-              run: yarn build:deploy
-
-            - name: Setup git user and npm
-              run: |
-                  git config --global user.name "Apify Release Bot"
-                  git config --global user.email "[email protected]"
-
-                  echo "access=public" > ~/.npmrc
-                  echo "//registry.npmjs.org/:_authToken=${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}" >> ~/.npmrc
-
-            - name: Publish to npm
-              run: |
-                cd ./packages/plugin
-                npm publish --access public
-              env:
-                  NPM_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}
-                  GIT_USER: '[email protected]:${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}'
-                  GH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+  release:
+    name: 'Release'
+    if:
+      (!contains(github.event.head_commit.message, '[skip ci]') &&
+      !contains(github.event.head_commit.message, 'docs:'))
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Enable corepack
+        run: |
+          corepack enable
+          corepack prepare yarn@stable --activate
+
+      - name: Activate cache for Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          cache: 'yarn'
+
+      - name: Install Dependencies
+        run: yarn
+
+      - name: Build
+        run: yarn build:deploy
+
+      - name: Setup git user and npm
+        run: |
+          git config --global user.name "Apify Release Bot"
+          git config --global user.email "[email protected]"
+
+          echo "access=public" > ~/.npmrc
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}" >> ~/.npmrc
+
+      - name: Publish to npm
+        run: |
+          cd ./packages/plugin
+          npm publish --access public
+        env:
+          NPM_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}
+          GIT_USER: '[email protected]:${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}'
+          GH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}

.gitignore

@@ -37,4 +37,10 @@ tmp/
 !.yarn/sdks
 !.yarn/versions
 .pnp.*
-*.tgz
+*.tgz
+
+# Python tooling
+pydoc-markdown-dump.json
+__pycache__/
+typedoc-types.raw
+typedoc-types-*.json

README.md

@@ -1,7 +1,8 @@
 # Apify's fork of `docusaurus-plugin-typedoc-api`
 
-This is a fork of [docusaurus-plugin-typedoc-api](https://github.com/milesj/docusaurus-plugin-typedoc-api)
-adjusted for our usecases with rendering library documentation in [Apify Docs](https://docs.apify.com).
+This is a fork of
+[docusaurus-plugin-typedoc-api](https://github.com/milesj/docusaurus-plugin-typedoc-api) adjusted
+for our usecases with rendering library documentation in [Apify Docs](https://docs.apify.com).
 
 ## Publishing
 

packages/plugin/src/components/ApiItem.tsx

@@ -55,19 +55,25 @@ export interface ApiItemProps extends Pick<DocItemProps, 'route'> {
 
 export const ApiOptionsContext = createContext({
 	hideInherited: false,
-	setHideInherited: (hideInherited: boolean) => {}
+	setHideInherited: (hideInherited: boolean) => {},
 });
 
 export default function ApiItem({ readme: Readme, route }: ApiItemProps) {
 	const [hideInherited, setHideInherited] = useState(false);
-	const apiOptions = useMemo(() => ({
-		hideInherited,
-		setHideInherited,
-	}), [hideInherited, setHideInherited]);
+	const apiOptions = useMemo(
+		() => ({
+			hideInherited,
+			setHideInherited,
+		}),
+		[hideInherited, setHideInherited],
+	);
 
 	const item = useRequiredReflection((route as unknown as { id: number }).id);
 	const reflections = useReflectionMap();
-	const toc = useMemo(() => extractTOC(item, reflections, hideInherited), [item, reflections, hideInherited]);
+	const toc = useMemo(
+		() => extractTOC(item, reflections, hideInherited),
+		[item, reflections, hideInherited],
+	);
 
 	// Pagination
 	const prevItem = useReflection(item.previousId);
@@ -117,7 +123,7 @@ export default function ApiItem({ readme: Readme, route }: ApiItemProps) {
 					</section>
 				)}
 
-				<Reflection reflection={item}  />
+				<Reflection reflection={item} />
 			</ApiItemLayout>
 		</ApiOptionsContext.Provider>
 	);

packages/plugin/src/components/ApiItemLayout.tsx

@@ -14,7 +14,7 @@ import TOC from '@theme/TOC';
 import TOCCollapsible from '@theme/TOCCollapsible';
 import { useBreadcrumbs } from '../hooks/useBreadcrumbs';
 import type { TOCItem } from '../types';
-import ApiOptionsLayout from './ApiOptionsLayout'
+import ApiOptionsLayout from './ApiOptionsLayout';
 import { VersionBanner } from './VersionBanner';
 
 export interface ApiItemLayoutProps extends Pick<DocItemProps, 'route'> {
@@ -72,7 +72,9 @@ export default function ApiItemLayout({
 							<div className={`${ThemeClassNames.docs.docMarkdown ?? ''} markdown`}>
 								<header>
 									<Heading as="h1">{heading}</Heading>
-									{module && <code className="tsd-header-member-fullname">{`${module}.${name}`}</code>}
+									{module && (
+										<code className="tsd-header-member-fullname">{`${module}.${name}`}</code>
+									)}
 								</header>
 
 								<MDXContent>{children}</MDXContent>

packages/plugin/src/components/ApiOptionsLayout.tsx

@@ -2,21 +2,23 @@ import { useCallback, useContext } from 'react';
 import { ApiOptionsContext } from './ApiItem';
 
 export default function ApiOptionsLayout({ className }: { className: string }) {
-  const { hideInherited, setHideInherited } = useContext(ApiOptionsContext);
-  const handleHideInherited = useCallback(() => {
-    setHideInherited(!hideInherited);
-  }, [hideInherited, setHideInherited]);
+	const { hideInherited, setHideInherited } = useContext(ApiOptionsContext);
+	const handleHideInherited = useCallback(() => {
+		setHideInherited(!hideInherited);
+	}, [hideInherited, setHideInherited]);
 
-  return (
-    <>
-      <div className={className}>
-        <div><b>Page Options</b></div>
-        <label>
-          <input checked={hideInherited} type="checkbox" onChange={handleHideInherited} />
-          <span>Hide Inherited</span>
-        </label>
-        <div />
-      </div>
-    </>
-  );
+	return (
+		<>
+			<div className={className}>
+				<div>
+					<b>Page Options</b>
+				</div>
+				<label>
+					<input checked={hideInherited} type="checkbox" onChange={handleHideInherited} />
+					<span>Hide Inherited</span>
+				</label>
+				<div />
+			</div>
+		</>
+	);
 }

packages/plugin/src/components/ApiPage.tsx

@@ -1,5 +1,3 @@
-/* eslint-disable no-param-reassign */
-
 import '@vscode/codicons/dist/codicon.css';
 import './styles.css';
 import { useMemo } from 'react';

packages/plugin/src/components/DefaultValue.tsx

@@ -34,7 +34,6 @@ export function DefaultValue({ comment, value, type }: DefaultValueProps) {
 		defaultTag = decode(marked(defaultTag));
 	}
 
-
 	if (!defaultTag && !value) {
 		return null;
 	}

packages/plugin/src/components/Flags.tsx

@@ -16,7 +16,7 @@ export function Flags({ flags }: FlagsProps) {
 	}
 
 	return (
-		<span className='tsd-flag-group'>
+		<span className="tsd-flag-group">
 			{Object.keys(flags)
 				.map(removePrefix)
 				.map((flag) => (

packages/plugin/src/components/Markdown.tsx

@@ -111,7 +111,6 @@ function convertAstToElements(ast: TokensList): React.ReactNode[] | undefined {
 	const elements: React.ReactNode[] = [];
 	let counter = 0;
 
-	// eslint-disable-next-line complexity
 	ast.forEach((token) => {
 		// Nested tokens aren't typed for some reason...
 		const children = (token as unknown as { tokens: TokensList }).tokens ?? [];

packages/plugin/src/components/Member.tsx

@@ -46,24 +46,26 @@ export function Member({ id }: MemberProps) {
 	}
 
 	return (
-		!shouldHideInherited && <section className="tsd-panel tsd-member">
-			<h3 className="tsd-panel-header">
-				<AnchorLink id={reflection.name} />
-				<SourceLink sources={reflection.sources} />
-				<Flags flags={reflection.flags} />
-				{escapeMdx(reflection.name)}
-				{isCommentWithModifiers(comment) && <CommentBadges comment={comment} />}
-			</h3>
+		!shouldHideInherited && (
+			<section className="tsd-panel tsd-member">
+				<h3 className="tsd-panel-header">
+					<AnchorLink id={reflection.name} />
+					<SourceLink sources={reflection.sources} />
+					<Flags flags={reflection.flags} />
+					{escapeMdx(reflection.name)}
+					{isCommentWithModifiers(comment) && <CommentBadges comment={comment} />}
+				</h3>
 
-			{content}
+				{content}
 
-			{reflection.groups?.map((group) => (
-				<Fragment key={group.title}>
-					{group.children?.map((child) =>
-						hasOwnDocument(child, reflections) ? null : <Member key={child} id={child} />,
-					)}
-				</Fragment>
-			))}
-		</section>
+				{reflection.groups?.map((group) => (
+					<Fragment key={group.title}>
+						{group.children?.map((child) =>
+							hasOwnDocument(child, reflections) ? null : <Member key={child} id={child} />,
+						)}
+					</Fragment>
+				))}
+			</section>
+		)
 	);
 }

packages/plugin/src/components/MemberGetterSetter.tsx

@@ -13,7 +13,6 @@ export interface MemberGetterSetterProps {
 	setter?: TSDDeclarationReflection['setSignature'];
 }
 
-// eslint-disable-next-line complexity
 export function MemberGetterSetter({ inPanel, getter, setter }: MemberGetterSetterProps) {
 	const minimal = useMinimalLayout();