From cbf0b8e41918f4b59df0f78fb838fe04b4dc29fe Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sun, 14 Jul 2024 06:35:35 +0200 Subject: [PATCH] [docs] fix changelog include (#12564) Use `include-read` instead of `source-read` for special content transform. In-particular, this fixes an issue that `docs/changes.rst` would not re-build, when `CHANGES.rst` was changed. --- CHANGES.rst | 4 ++-- doc/conf.py | 16 ++++------------ 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index fdc7ecfc9..97252f732 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -28,9 +28,9 @@ Features added .. rst-class:: compact -* Add ``level`` option to :rst:dir:`rubric` directive. +* #12506 Add ``level`` option to :rst:dir:`rubric` directive. Patch by Chris Sewell. -* Add optional ``description`` argument to +* #12549 Add optional ``description`` argument to :meth:`~sphinx.application.Sphinx.add_config_value`. Patch by Chris Sewell. * #11165: Support the `officially recommended`_ ``.jinja`` suffix for template diff --git a/doc/conf.py b/doc/conf.py index 893d48626..9ca3e508b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -258,25 +258,17 @@ def parse_event(env, sig, signode): return name -def linkify_issues_in_changelog(app, docname, source): +def linkify_issues_in_changelog(app, path, docname, source): """Linkify issue references like #123 in changelog to GitHub.""" if docname == 'changes': - changelog_path = os.path.join(os.path.dirname(__file__), '../CHANGES.rst') - # this path trickery is needed because this script can - # be invoked with different working directories: - # * running make in docs/ - # * running tox -e docs in the repo root dir - - with open(changelog_path, encoding='utf-8') as f: - changelog = f.read() def linkify(match): url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1] return f'`{match[0]} <{url}>`_' - linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog) + linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, source[0]) - source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog) + source[0] = linkified_changelog REDIRECT_TEMPLATE = """ @@ -325,7 +317,7 @@ def setup(app: Sphinx) -> None: from sphinx.util.docfields import GroupedField app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) - app.connect('source-read', linkify_issues_in_changelog) + app.connect('include-read', linkify_issues_in_changelog) app.connect('build-finished', build_redirects) fdesc = GroupedField('parameter', label='Parameters', names=['param'], can_collapse=True) app.add_object_type(