James Clark 7cc4c09269 docs: automarkup.py: Fix invalid HTML link output and broken URI fragments ... Since commit d18b01789a ("docs: Add automatic cross-reference for documentation pages"), references that were already explicitly defined with "ref:" and referred to other pages with a path have been doubled. This is reported as the following error by Firefox: Start tag "a" seen but an element of the same type was already open. End tag "a" violates nesting rules. As well as the invalid HTML, this also obscures the URI fragment links to subsections because the second link overrides the first. For example on the page admin-guide/hw-vuln/mds.html the last link should be to the "Default Mitigations" subsection using a # URI fragment: admin-guide/hw-vuln/l1tf.html#default-mitigations But it is obsured by a second link to the whole page: admin-guide/hw-vuln/l1tf.html The full HTML with the double <a> tags looks like this: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref"> <a class="reference internal" href="l1tf.html"> <span class="doc">L1TF - L1 Terminal Fault</span> </a> </span> </a> After this commit, there is only a single link: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span> </a> Now that the second link is removed, the browser correctly jumps to the default-mitigations subsection when clicking the link. The fix is to check that nodes in the document to be modified are not already references. A reference is counted as any text that is a descendant of a reference type node. Only plain text should be converted to new references, otherwise the doubling occurs. Testing ======= * Test that the build stdout is the same (ignoring ordering), and that no new warnings are printed. * Diff all .html files and check that the only modifications occur to the bad double links. * The auto linking of bare references to pages without "ref:" is still working. Fixes: d18b01789a ("docs: Add automatic cross-reference for documentation pages") Reviewed-by: Nícolas F. R. A. Prado <n@nfraprado.net> Signed-off-by: James Clark <james.clark@arm.com> Link: https://lore.kernel.org/r/20220105143640.330602-2-james.clark@arm.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>		2022-01-07 09:32:58 -07:00
..
automarkup.py	docs: automarkup.py: Fix invalid HTML link output and broken URI fragments	2022-01-07 09:32:58 -07:00
cdomain.py	Move our minimum Sphinx version to 1.7	2021-02-01 16:29:12 -07:00
kernel_abi.py	Documentation/sphinx: fix typos of "its"	2021-12-23 12:42:47 -07:00
kernel_feat.py	Documentation/sphinx: fix typos of "its"	2021-12-23 12:42:47 -07:00
kernel_include.py	docs: sphinx-extensions: add metadata parallel-safe	2016-09-01 08:19:02 -06:00
kerneldoc.py	Move our minimum Sphinx version to 1.7	2021-02-01 16:29:12 -07:00
kernellog.py	Move our minimum Sphinx version to 1.7	2021-02-01 16:29:12 -07:00
kfigure.py	Docs: drop Python 2 support	2021-02-01 17:17:14 -07:00
load_config.py	docs: load_config.py: ensure subdirs end with "/"	2019-07-19 08:49:27 -03:00
maintainers_include.py	Docs: drop Python 2 support	2021-02-01 17:17:14 -07:00
parallel-wrapper.sh	docs: Fix empty parallelism argument	2020-02-25 03:11:04 -07:00
parse-headers.pl	tweewide: Fix most Shebang lines	2020-12-08 23:30:04 +09:00
requirements.txt	docs: sphinx-requirements: Move sphinx_rtd_theme to top	2021-08-12 09:15:38 -06:00
rstFlatTable.py	docs: sphinx: Fix couple of spellings in the file rstFlatTable.py	2021-03-06 17:36:50 -07:00