diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt index 844451fd8a8..526dcb8d353 100644 --- a/doc/_static/conf.py.txt +++ b/doc/_static/conf.py.txt @@ -319,6 +319,10 @@ texinfo_documents = [ # # texinfo_no_detailmenu = False +# If false, do not generate in manual @ref nodes. +# +# texinfo_emit_document_references = False + # -- A random example ----------------------------------------------------- import sys, os diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 0ae9cd5dfc3..43309c2e662 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2484,6 +2484,13 @@ These options influence Texinfo output. .. versionadded:: 1.1 +.. confval:: texinfo_emit_document_references + + If false, do not generate inline references in a document. That makes + an info file more readable with stand-alone reader (``info``). + Default is ``True`` + + .. versionadded:: 4.2.0 .. _qthelp-options: diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py index ee10d58c350..386e6471e36 100644 --- a/sphinx/builders/texinfo.py +++ b/sphinx/builders/texinfo.py @@ -211,6 +211,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value('texinfo_domain_indices', True, None, [list]) app.add_config_value('texinfo_show_urls', 'footnote', None) app.add_config_value('texinfo_no_detailmenu', False, None) + app.add_config_value('texinfo_emit_document_references', True, None) return { 'version': 'builtin', diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index 6df558323f9..263c141bf56 100644 --- a/sphinx/writers/texinfo.py +++ b/sphinx/writers/texinfo.py @@ -545,7 +545,10 @@ def add_anchor(self, id: str, node: Node) -> None: def add_xref(self, id: str, name: str, node: Node) -> None: name = self.escape_menu(name) sid = self.get_short_id(id) - self.body.append('@ref{%s,,%s}' % (sid, name)) + if self.config.texinfo_emit_document_references: + self.body.append('@ref{%s,,%s}' % (sid, name)) + else: + self.body.append(name) self.referenced_ids.add(sid) self.referenced_ids.add(self.escape_id(id)) diff --git a/tests/test_build_texinfo.py b/tests/test_build_texinfo.py index 546ccaabf4b..23a3aa6798b 100644 --- a/tests/test_build_texinfo.py +++ b/tests/test_build_texinfo.py @@ -112,3 +112,17 @@ def test_texinfo_escape_id(app, status, warning): assert translator.escape_id('Hello(world)') == 'Hello world' assert translator.escape_id('Hello world.') == 'Hello world' assert translator.escape_id('.') == '.' + + +@pytest.mark.sphinx('texinfo') +def test_texinfo_xrefs(app, status, warning): + app.builder.build_all() + output = (app.outdir / 'sphinxtests.texi').read_text() + assert re.search(r'@ref{\w+,,--plugin\.option}', output) + + # Now rebuild it without xrefs + app.config.texinfo_emit_document_references = False + app.builder.build_all() + output = (app.outdir / 'sphinxtests.texi').read_text() + assert not re.search(r'@ref{\w+,,--plugin\.option}', output) + assert 'Link to perl +p, --ObjC++, --plugin.option, create-auth-token, arg and -j' in output