docs: remove redundant transformDocs.js and pydoc-markdown setup

website/build_api_reference.sh

@@ -1,21 +1,4 @@
 #!/bin/bash
 
-# On macOS, sed requires a space between -i and '' to specify no backup should be done
-# On Linux, sed requires no space between -i and '' to specify no backup should be done
-sed_no_backup() {
-    if [[ $(uname) = "Darwin" ]]; then
-        sed -i '' "$@"
-    else
-        sed -i'' "$@"
-    fi
-}
-
-# Create docspec dump of this package's source code through pydoc-markdown
-pydoc-markdown --quiet --dump > docspec-dump.jsonl
-sed_no_backup "s#${PWD}/..#REPO_ROOT_PLACEHOLDER#g" docspec-dump.jsonl
-
 # Generate import shortcuts from the modules
 python generate_module_shortcuts.py
-
-# Transform the docpec dumps into Typedoc-compatible docs tree
-node transformDocs.js

website/docusaurus.config.js

@@ -3,9 +3,29 @@ const { join, resolve } = require('node:path');
 const { config } = require('@apify/docs-theme');
 
 const { externalLinkProcessor } = require('./tools/utils/externalLink');
-const { groupSort } = require('./transformDocs.js');
 const versions = require('./versions.json');
 
+const GROUP_ORDER = [
+    'Apify API clients',
+    'HTTP clients',
+    'Resource clients',
+    'Errors',
+    'Models',
+    'Other',
+];
+
+const groupSort = (g1, g2) => {
+    const i1 = GROUP_ORDER.indexOf(g1);
+    const i2 = GROUP_ORDER.indexOf(g2);
+    // Both known – sort by defined order
+    if (i1 !== -1 && i2 !== -1) return i1 - i2;
+    // Unknown groups go after known ones
+    if (i1 !== -1) return -1;
+    if (i2 !== -1) return 1;
+    // Both unknown – alphabetical
+    return g1.localeCompare(g2);
+};
+
 const { absoluteUrl } = config;
 
 /** @type {Partial<import('@docusaurus/types').DocusaurusConfig>} */
@@ -46,19 +66,21 @@ module.exports = {
                     title: 'API Client for Python',
                     items: [
                         {
-                            to: 'docs',
+                            type: 'doc',
+                            docId: 'introduction/introduction',
                             label: 'Docs',
                             position: 'left',
                             activeBaseRegex: '/docs(?!/changelog)',
                         },
                         {
-                            to: '/reference',
+                            type: 'custom-versioned-reference',
                             label: 'Reference',
                             position: 'left',
                             activeBaseRegex: '/reference',
                         },
                         {
-                            to: 'docs/changelog',
+                            type: 'doc',
+                            docId: 'changelog',
                             label: 'Changelog',
                             position: 'left',
                             activeBaseRegex: '/docs/changelog',
@@ -109,7 +131,6 @@ module.exports = {
                 typedocOptions: {
                     excludeExternals: false,
                 },
-                pathToCurrentVersionTypedocJSON: `${__dirname}/api-typedoc-generated.json`,
                 sortSidebar: groupSort,
                 routeBasePath: 'reference',
                 python: true,

website/src/theme/NavbarItem/ComponentTypes.js

@@ -0,0 +1,7 @@
+import OriginalComponentTypes from '@theme-original/NavbarItem/ComponentTypes';
+import VersionedReferenceNavbarItem from './VersionedReferenceNavbarItem';
+
+export default {
+    ...OriginalComponentTypes,
+    'custom-versioned-reference': VersionedReferenceNavbarItem,
+};

website/src/theme/NavbarItem/VersionedReferenceNavbarItem.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import { useDocsVersionCandidates } from '@docusaurus/plugin-content-docs/client';
+import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+
+/* eslint-disable react/prop-types */
+export default function VersionedReferenceNavbarItem({ docsPluginId, ...props }) {
+    const [version] = useDocsVersionCandidates(docsPluginId);
+
+    // Latest version → /reference, "current" (next) → /reference/next, others → /reference/{name}
+    let to = '/reference';
+    if (!version.isLast) {
+        to = `/reference/${version.name === 'current' ? 'next' : version.name}`;
+    }
+
+    return <DefaultNavbarItem {...props} to={to} />;
+}