Edited Presto documentation files to fix doc build errors of the same type as the following example in the Presto documentation build (errors taken from a local doc build):
/Users/steveburnett/Documents/GitHub/presto/presto-docs/src/main/sphinx/functions/aggregate.rst:15: WARNING: js:func reference target not found: count
In general, adding a ! to a reference content causes it to not try to resolve, and instead only display with the appropriate formatting/semantics. This is useful for cases where the reference is not intended to resolve, such as those to objects that are deliberately undocumented, those that are removed (e.g. as noted in the What’s New), or examples (e.g. :class:!AnExampleClass). Versus some sort of manual whitelist, this doesn’t require any additional infra, is quick to add to existing usages, is more efficient as it doesn’t waste time trying to resolve those references and then printing a warning, and ensures those warnings aren’t emitted in the first place.
Applying this solution, I edited presto-docs/src/main/sphinx/functions/aggregate.rst (from the example error above) as follows:
:func:`count`
to
:func:`!count`
which caused the WARNING: js:func reference target not found: count error to not be generated.
The display of the function name in the doc build is unaffected.
I then applied the same fix to the rest of the errors of this type that were generated in a local doc build.
While this PR is large, I limited its scope to fixing only errors of this one type to simplify the work of the reviewer.
Motivation and Context
Like the doc build errors I fixed in #22876 and #22985, these errors don't stop the build but they're annoying, and these are easy and low-risk fixes.
Impact
Documentation.
Test Plan
Local doc builds.
before the changes in this PR:
build succeeded, 635 warnings.
after the changes in this PR:
build succeeded, 25 warnings.
Description
Edited Presto documentation files to fix doc build errors of the same type as the following example in the Presto documentation build (errors taken from a local doc build):
/Users/steveburnett/Documents/GitHub/presto/presto-docs/src/main/sphinx/functions/aggregate.rst:15: WARNING: js:func reference target not found: countAs found in Broken references in Sphinx documentation:
In general, adding a ! to a reference content causes it to not try to resolve, and instead only display with the appropriate formatting/semantics. This is useful for cases where the reference is not intended to resolve, such as those to objects that are deliberately undocumented, those that are removed (e.g. as noted in the What’s New), or examples (e.g. :class:
!AnExampleClass). Versus some sort of manual whitelist, this doesn’t require any additional infra, is quick to add to existing usages, is more efficient as it doesn’t waste time trying to resolve those references and then printing a warning, and ensures those warnings aren’t emitted in the first place.Applying this solution, I edited
presto-docs/src/main/sphinx/functions/aggregate.rst(from the example error above) as follows::func:`count`to
:func:`!count`which caused the
WARNING: js:func reference target not found: counterror to not be generated.The display of the function name in the doc build is unaffected.
I then applied the same fix to the rest of the errors of this type that were generated in a local doc build.
While this PR is large, I limited its scope to fixing only errors of this one type to simplify the work of the reviewer.
Motivation and Context
Like the doc build errors I fixed in #22876 and #22985, these errors don't stop the build but they're annoying, and these are easy and low-risk fixes.
Impact
Documentation.
Test Plan
Local doc builds.
before the changes in this PR: build succeeded, 635 warnings.
after the changes in this PR: build succeeded, 25 warnings.
Contributor checklist
Release Notes