From 0aeb40092c0bbd256ad099ae3544097224614a8a Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Tue, 12 Aug 2025 09:51:39 +0200 Subject: [PATCH 1/3] docs: attempt to fix changelog --- Makefile | 12 ++++++++-- website/docusaurus.config.js | 1 + website/package-lock.json | 4 ++-- website/package.json | 3 ++- website/tools/patch-typedoc-plugin.js | 33 +++++++++++++++++++++++++++ 5 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 website/tools/patch-typedoc-plugin.js diff --git a/Makefile b/Makefile index 0874e6d0..51e812b4 100644 --- a/Makefile +++ b/Makefile @@ -52,8 +52,16 @@ fix-async-docstrings: build-api-reference: cd website && uv run ./build_api_reference.sh -build-docs: +PYTHON_DOCS_VERSION ?= 3.13 + +## Helper target to ensure a suitable Python version for docs (type parsing needs >=3.11) +ensure-docs-python: + @python -c 'import sys; import re; v=sys.version_info;\ + print(f"Using system Python {v.major}.{v.minor}") if (v.major>3 or (v.major==3 and v.minor>=11)) else (_ for _ in ()).throw(SystemExit(1))' \ + || (echo "Local python is too old, trying uv to fetch Python $(PYTHON_DOCS_VERSION)" && uv python install $(PYTHON_DOCS_VERSION)) + +build-docs: ensure-docs-python cd website && uv run npm clean-install && uv run npm run build -run-docs: build-api-reference +run-docs: build-api-reference ensure-docs-python cd website && uv run npm clean-install && uv run npm run start diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 06e897c0..8d0c6c73 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -40,6 +40,7 @@ module.exports = { [ '@apify/docs-theme', { + changelogFromRoot: true, subNavbar: { title: 'API Client for Python', items: [ diff --git a/website/package-lock.json b/website/package-lock.json index b23d7450..1b170fb8 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -6,8 +6,8 @@ "": { "name": "apify-client-python", "dependencies": { - "@apify/docs-theme": "^1.0.181", - "@apify/docusaurus-plugin-typedoc-api": "^4.4.3", + "@apify/docs-theme": "^1.0.185", + "@apify/docusaurus-plugin-typedoc-api": "^4.4.6", "@docusaurus/core": "^3.8.1", "@docusaurus/faster": "^3.8.1", "@docusaurus/plugin-client-redirects": "^3.8.1", diff --git a/website/package.json b/website/package.json index e0aee0cd..b714a905 100644 --- a/website/package.json +++ b/website/package.json @@ -18,7 +18,8 @@ "lint:md": "markdownlint --config ../.markdownlint.yaml '../docs/**/*.md' '../docs/**/*.mdx' --ignore '../docs/changelog.md'", "lint:md:fix": "npm run lint:md -- --fix", "lint:code": "eslint .", - "lint:code:fix": "eslint . --fix" + "lint:code:fix": "eslint . --fix", + "postinstall": "node ./tools/patch-typedoc-plugin.js" }, "dependencies": { "@apify/docs-theme": "^1.0.181", diff --git a/website/tools/patch-typedoc-plugin.js b/website/tools/patch-typedoc-plugin.js new file mode 100644 index 00000000..ea07f6ee --- /dev/null +++ b/website/tools/patch-typedoc-plugin.js @@ -0,0 +1,33 @@ +// Ensures typedoc-types-parsed.json exists before docusaurus start. +const fs = require('fs'); +const path = require('path'); + +const baseDir = path.join(__dirname, '..', 'node_modules', '@apify', 'docusaurus-plugin-typedoc-api', 'lib', 'plugin', 'python', 'type-parsing'); +const rawFile = path.join(baseDir, 'typedoc-types.raw'); +const parsedFile = path.join(baseDir, 'typedoc-types-parsed.json'); +const scriptFile = path.join(__dirname, '..', 'node_modules', '@apify', 'docusaurus-plugin-typedoc-api', 'python-scripts', 'type-parsing', 'parse_types.py'); + +function ensureParsed() { + if (fs.existsSync(parsedFile)) return; + if (!fs.existsSync(rawFile)) { + // create empty raw file so parser produces empty object + fs.writeFileSync(rawFile, '[]', 'utf8'); + } + try { + const { spawnSync } = require('child_process'); + const res = spawnSync('python', [scriptFile, rawFile]); + if (res.status !== 0) { + console.warn('[patch-typedoc-plugin] Failed to generate parsed types:', res.stderr?.toString()); + if (!fs.existsSync(parsedFile)) { + fs.writeFileSync(parsedFile, '{}', 'utf8'); + } + } + } catch (e) { + console.warn('[patch-typedoc-plugin] Error generating parsed types', e); + if (!fs.existsSync(parsedFile)) { + fs.writeFileSync(parsedFile, '{}', 'utf8'); + } + } +} + +ensureParsed(); From ea517f74d204abce98700399877e5f3dd8111dac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= Date: Tue, 12 Aug 2025 11:07:02 +0200 Subject: [PATCH 2/3] Revert "docs: attempt to fix changelog" This reverts commit 0aeb40092c0bbd256ad099ae3544097224614a8a. --- Makefile | 12 ++-------- website/docusaurus.config.js | 1 - website/package-lock.json | 4 ++-- website/package.json | 3 +-- website/tools/patch-typedoc-plugin.js | 33 --------------------------- 5 files changed, 5 insertions(+), 48 deletions(-) delete mode 100644 website/tools/patch-typedoc-plugin.js diff --git a/Makefile b/Makefile index 51e812b4..0874e6d0 100644 --- a/Makefile +++ b/Makefile @@ -52,16 +52,8 @@ fix-async-docstrings: build-api-reference: cd website && uv run ./build_api_reference.sh -PYTHON_DOCS_VERSION ?= 3.13 - -## Helper target to ensure a suitable Python version for docs (type parsing needs >=3.11) -ensure-docs-python: - @python -c 'import sys; import re; v=sys.version_info;\ - print(f"Using system Python {v.major}.{v.minor}") if (v.major>3 or (v.major==3 and v.minor>=11)) else (_ for _ in ()).throw(SystemExit(1))' \ - || (echo "Local python is too old, trying uv to fetch Python $(PYTHON_DOCS_VERSION)" && uv python install $(PYTHON_DOCS_VERSION)) - -build-docs: ensure-docs-python +build-docs: cd website && uv run npm clean-install && uv run npm run build -run-docs: build-api-reference ensure-docs-python +run-docs: build-api-reference cd website && uv run npm clean-install && uv run npm run start diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8d0c6c73..06e897c0 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -40,7 +40,6 @@ module.exports = { [ '@apify/docs-theme', { - changelogFromRoot: true, subNavbar: { title: 'API Client for Python', items: [ diff --git a/website/package-lock.json b/website/package-lock.json index 1b170fb8..b23d7450 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -6,8 +6,8 @@ "": { "name": "apify-client-python", "dependencies": { - "@apify/docs-theme": "^1.0.185", - "@apify/docusaurus-plugin-typedoc-api": "^4.4.6", + "@apify/docs-theme": "^1.0.181", + "@apify/docusaurus-plugin-typedoc-api": "^4.4.3", "@docusaurus/core": "^3.8.1", "@docusaurus/faster": "^3.8.1", "@docusaurus/plugin-client-redirects": "^3.8.1", diff --git a/website/package.json b/website/package.json index b714a905..e0aee0cd 100644 --- a/website/package.json +++ b/website/package.json @@ -18,8 +18,7 @@ "lint:md": "markdownlint --config ../.markdownlint.yaml '../docs/**/*.md' '../docs/**/*.mdx' --ignore '../docs/changelog.md'", "lint:md:fix": "npm run lint:md -- --fix", "lint:code": "eslint .", - "lint:code:fix": "eslint . --fix", - "postinstall": "node ./tools/patch-typedoc-plugin.js" + "lint:code:fix": "eslint . --fix" }, "dependencies": { "@apify/docs-theme": "^1.0.181", diff --git a/website/tools/patch-typedoc-plugin.js b/website/tools/patch-typedoc-plugin.js deleted file mode 100644 index ea07f6ee..00000000 --- a/website/tools/patch-typedoc-plugin.js +++ /dev/null @@ -1,33 +0,0 @@ -// Ensures typedoc-types-parsed.json exists before docusaurus start. -const fs = require('fs'); -const path = require('path'); - -const baseDir = path.join(__dirname, '..', 'node_modules', '@apify', 'docusaurus-plugin-typedoc-api', 'lib', 'plugin', 'python', 'type-parsing'); -const rawFile = path.join(baseDir, 'typedoc-types.raw'); -const parsedFile = path.join(baseDir, 'typedoc-types-parsed.json'); -const scriptFile = path.join(__dirname, '..', 'node_modules', '@apify', 'docusaurus-plugin-typedoc-api', 'python-scripts', 'type-parsing', 'parse_types.py'); - -function ensureParsed() { - if (fs.existsSync(parsedFile)) return; - if (!fs.existsSync(rawFile)) { - // create empty raw file so parser produces empty object - fs.writeFileSync(rawFile, '[]', 'utf8'); - } - try { - const { spawnSync } = require('child_process'); - const res = spawnSync('python', [scriptFile, rawFile]); - if (res.status !== 0) { - console.warn('[patch-typedoc-plugin] Failed to generate parsed types:', res.stderr?.toString()); - if (!fs.existsSync(parsedFile)) { - fs.writeFileSync(parsedFile, '{}', 'utf8'); - } - } - } catch (e) { - console.warn('[patch-typedoc-plugin] Error generating parsed types', e); - if (!fs.existsSync(parsedFile)) { - fs.writeFileSync(parsedFile, '{}', 'utf8'); - } - } -} - -ensureParsed(); From 55267fb999c3295ac8fc4076991dca3acc91bdcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= Date: Tue, 12 Aug 2025 12:16:40 +0200 Subject: [PATCH 3/3] chore: use `git-cliff` generated changelog in the docs --- website/docusaurus.config.js | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 06e897c0..8d0c6c73 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -40,6 +40,7 @@ module.exports = { [ '@apify/docs-theme', { + changelogFromRoot: true, subNavbar: { title: 'API Client for Python', items: [