From 3766314967e4f8a7869528d3693f61b746fa3bd3 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 28 Apr 2017 19:15:17 +1000 Subject: [PATCH 1/2] bpo-30052: Always regenerate cross-references The patch for bpo-30052 changed the preferred link target for :func:`bytes` and :func`bytearray` references to be the respective type definitions rather than the corresponding builtin function entries. This patch changes the daily documentation builds to disable the output caching in Sphinx, in order to ensure that cross-reference changes like this one are reliably picked up and applied automatically after merging. --- Doc/Makefile | 9 +++++++-- Misc/NEWS | 9 +++++++++ 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index 94697f95671894..ae59f3294f1c06 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -159,15 +159,20 @@ serve: ../Tools/scripts/serve.py build/html # Targets for daily automated doc build +# By default, Sphinx only rebuilds pages where the page content has changed. +# This means it doesn't always pick up changes to preferred link targets, etc +# To ensure such changes are picked up, we build the published docs with +# `-E` (to ignore the cached environment) and `-a` (to ignore already existing +# output files) # for development releases: always build autobuild-dev: - make dist SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' + make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1' -make suspicious # for quick rebuilds (HTML only) autobuild-dev-html: - make html SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' + make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1' # for stable releases: only build if not in pre-release stage (alpha, beta) # release candidate downloads are okay, since the stable tree can be in that stage diff --git a/Misc/NEWS b/Misc/NEWS index 71db0ee46b0dc4..56975362ae398b 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -984,6 +984,15 @@ C API Documentation ------------- +- Issue #30052: the link targets for ``:func:\`bytes\``` and + ``:func:\`bytearray\``` are now their respective type definitions, rather + than the corresponding builtin function entries. Use ``:ref:\`func-bytes\``` + and ``:ref:\`func-bytes\``` to reference the latter. + + In order to ensure this and future cross-reference updates are applied + automatically, the daily documentation builds now disable the default + output caching features in Sphinx. + - bpo-26985: Add missing info of code object in inspect documentation. - bpo-19824, bpo-20314, bpo-12518: Improve the documentation for, and links From f0b3c0b9bf2273ff33bafa3fc72318decfd89d35 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Mon, 1 May 2017 17:20:54 +1000 Subject: [PATCH 2/2] Don't attempt to escape markup in NEWS --- Misc/NEWS | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Misc/NEWS b/Misc/NEWS index 56975362ae398b..99911068b30db3 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -984,10 +984,10 @@ C API Documentation ------------- -- Issue #30052: the link targets for ``:func:\`bytes\``` and - ``:func:\`bytearray\``` are now their respective type definitions, rather - than the corresponding builtin function entries. Use ``:ref:\`func-bytes\``` - and ``:ref:\`func-bytes\``` to reference the latter. +- Issue #30052: the link targets for :func:`bytes` and + :func:`bytearray` are now their respective type definitions, rather + than the corresponding builtin function entries. Use :ref:`bytes ` + and :ref:`bytearray ` to reference the latter. In order to ensure this and future cross-reference updates are applied automatically, the daily documentation builds now disable the default