From 7485a536f6405ef1b400c2d73e6944a30581d3c3 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Thu, 18 Jun 2026 14:18:16 +0200 Subject: [PATCH 1/2] fix: drop CrossrefProcessor that corrupts URL fragments in docstrings --- python-scripts/docspec-gen/generate_ast.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/python-scripts/docspec-gen/generate_ast.py b/python-scripts/docspec-gen/generate_ast.py index f1e06a38..8c77129b 100755 --- a/python-scripts/docspec-gen/generate_ast.py +++ b/python-scripts/docspec-gen/generate_ast.py @@ -7,7 +7,6 @@ from pydoc_markdown.interfaces import Context from pydoc_markdown.contrib.loaders.python import PythonLoader from pydoc_markdown.contrib.processors.filter import FilterProcessor -from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor from google_docstring_processor import ApifyGoogleProcessor from docspec import dump_module @@ -43,15 +42,20 @@ def main(): documented_only=False, skip_empty_modules=False, ) - crossref = CrossrefProcessor() google = ApifyGoogleProcessor() loader.init(context) filter.init(context) google.init(context) - crossref.init(context) - processors = [filter, google, crossref] + # NOTE: pydoc-markdown's CrossrefProcessor is intentionally omitted. It is always run with + # resolver=None here, so it can never turn a `#ref` into an actual link — it only falls back to + # wrapping the ref in backticks. Worse, its regex matches any `#word` preceded by a non-word + # char (e.g. the `/#` in `.../dockerfile_best-practices/#leverage-build-cache`), corrupting URL + # fragments into broken links like ``...best-practices/`leverage`-build-cache``. The Apify + # docstrings don't use `#ref` cross-references, so dropping it is pure win (and matches the + # griffe-based extractor, which doesn't run it either). + processors = [filter, google] dump = [] From 5a3f6cb1169c95a45dc446db05161497c3a53257 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= Date: Fri, 19 Jun 2026 13:18:21 +0200 Subject: [PATCH 2/2] chore: remove comments from scripts --- python-scripts/docspec-gen/generate_ast.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/python-scripts/docspec-gen/generate_ast.py b/python-scripts/docspec-gen/generate_ast.py index 8c77129b..0c0b1a08 100755 --- a/python-scripts/docspec-gen/generate_ast.py +++ b/python-scripts/docspec-gen/generate_ast.py @@ -48,13 +48,6 @@ def main(): filter.init(context) google.init(context) - # NOTE: pydoc-markdown's CrossrefProcessor is intentionally omitted. It is always run with - # resolver=None here, so it can never turn a `#ref` into an actual link — it only falls back to - # wrapping the ref in backticks. Worse, its regex matches any `#word` preceded by a non-word - # char (e.g. the `/#` in `.../dockerfile_best-practices/#leverage-build-cache`), corrupting URL - # fragments into broken links like ``...best-practices/`leverage`-build-cache``. The Apify - # docstrings don't use `#ref` cross-references, so dropping it is pure win (and matches the - # griffe-based extractor, which doesn't run it either). processors = [filter, google] dump = []