First 50 patches remove the use of raw HTML passthrough in
formatdomain.rst, which is the only outstanding place which still does.

Most of the work was done by a ad-hoc bash script, but manual  tweaks
were needed. Since this series also contains a test script which
validates linking I'm not going to publish the conversion script.

The rest of the series then cleans up pre-existing broken links and adds
the aforementioned checker script.

One more change is to prevent the use of external references in RST to
refer to the same file. All usage was converted to local references and
a syntax check was added.

One slight drawback of the checker script is that it works on generated
HTML files and thus the error message contains the output file name and
not the source RST document.

Output after the fixes can be browsed at:

https://gitlab.com/pipo.sk/libvirt/-/jobs/2528184702/artifacts/browse/website/

Peter Krempa (67):
  docs: formatdomain: Remove 'elements' anchor
  docs: formatdomain: Remove 'elementsMetadata' anchor
  docs: formatdomain: Remove 'elementsOS' anchor
  docs: formatdomain: Remove 'elementsOSBIOS' anchor
  docs: formatdomain: Remove 'elementsOSContainer' anchor
  docs: formatdomain: Remove 'elementsSysinfo' anchor
  docs: formatdomain: Remove 'elementsCPUAllocation' anchor
  docs: formatdomain: Remove 'elementsIOThreadsAllocation' anchor
  docs: formatdomain: Remove 'elementsCPUTuning' anchor
  docs: formatdomain: Remove 'elementsMemoryAllocation' anchor
  docs: formatdomain: Remove 'elementsMemoryBacking' anchor
  docs: formatdomain: Remove 'elementsMemoryTuning' anchor
  docs: formatdomain: Remove 'elementsNUMATuning' anchor
  docs: formatdomain: Remove 'elementsBlockTuning' anchor
  docs: formatdomain: Remove 'elementsCPU' anchor
  docs: formatdomain: Remove 'hmat' anchor
  docs: formatdomain: Remove 'elementsEvents' anchor
  docs: formatdomain: Remove 'elementsFeatures' anchor
  docs: formatdomain: Remove 'elementsDevices' anchor
  docs: formatdomain: Remove 'elementsDisks' anchor
  docs: formatdomain: Remove 'elementsAddress' anchor
  docs: formatdomain: Remove 'elementsVirtio' anchor
  docs: formatdomain: Remove 'elementsVirtioTransitional' anchor
  docs: formatdomain: Remove 'elementsControllers' anchor
  docs: formatdomain: Remove 'elementsHostDev' anchor
  docs: formatdomain: Remove 'elementsNICS' anchor
  docs: formatdomain: Remove 'elementsNICSDirect' anchor
  docs: formatdomain: Remove 'elementsNICSTargetOverride' anchor
  docs: formatdomain: Remove 'elementQoS' anchor
  docs: formatdomain: Remove 'elementVlanTag' anchor
  docs: formatdomain: Remove 'elementPort' anchor
  docs: formatdomain: Remove 'mtu' anchor
  docs: formatdomain: Remove 'coalesce' anchor
  docs: formatdomain: Remove 'elementVhostuser' anchor
  docs: formatdomain: Remove 'elementsGraphics' anchor
  docs: formatdomain: Remove 'elementsVideo' anchor
  docs: formatdomain: Remove 'elementsConsole' anchor
  docs: formatdomain: Remove 'elementCharSerial' anchor
  docs: formatdomain: Remove 'elementCharSerialAndConsole' anchor
  docs: formatdomain: Remove 'elementsCharHostInterface' anchor
  docs: formatdomain: Remove 'elementsCharHost' anchor
  docs: formatdomain: Remove 'elementsAudio' anchor
  docs: formatdomain: Remove 'elementsTpm' anchor
  docs: formatdomain: Remove 'elementsMemory' anchor
  docs: formatdomain: Remove 'elementsIommu' anchor
  docs: formatdomain: Remove 'vsock' anchor
  docs: formatdomain: Remove 'seclabel' anchor
  docs: formatdomain: Remove 'keywrap' anchor
  docs: formatdomain: Remove 'launchSecurity' anchor
  docs: formatdomain: Remove the 'anchor' role
  docs: formatdomain: Use local reference directly
  docs: uri: Fix link to libvirtd configuration section
  syntax-check: Add check prohibiting remote reference to local file
  docs: page.xsl: Fix link to 'mailing-lists' section
  docs: domainstatecapture: Fix broken links
  docs: rpc: Fix broken headings
  docs: formatcaps: Fix anchors of links into formatdomain.rst
  scripts: hvsupport: Remove link into the 'html' directory
  docs: Fix link to 'tlscerts' article
  docs: Remove extra leading slash in 'api' and 'formatdomaincaps' pages
  docs: Fix links in kbase/internals
  docs: kbase/kvm-realtime: Fix few links
  docs: kbase/tlscerts: Fix links
  docs: remote: Fix anchor names in links to uri.html
  uri: Fix link to qemu KVM example config
  docs: formatstorageencryption: Use correct anchor into formatsecret
    page
  docs: Add HTML reference checker

 build-aux/syntax-check.mk          |   7 +
 docs/api.rst                       |   2 +-
 docs/docs.rst                      |   2 +-
 docs/drvlxc.rst                    |   2 +-
 docs/formatbackup.rst              |   6 +-
 docs/formatcaps.rst                |  10 +-
 docs/formatcheckpoint.rst          |   2 +-
 docs/formatdomain.rst              | 360 ++++++++++++-----------------
 docs/formatdomaincaps.rst          |  20 +-
 docs/formatnetwork.rst             |   8 +-
 docs/formatnetworkport.rst         |   4 +-
 docs/formatnode.rst                |   2 +-
 docs/formatsecret.rst              |  12 +-
 docs/formatsnapshot.rst            |   8 +-
 docs/formatstorageencryption.rst   |   2 +-
 docs/kbase/domainstatecapture.rst  |  12 +-
 docs/kbase/internals/eventloop.rst |   2 +-
 docs/kbase/internals/migration.rst |   2 +-
 docs/kbase/internals/rpc.rst       |  16 +-
 docs/kbase/kvm-realtime.rst        |  10 +-
 docs/kbase/launch_security_sev.rst |   2 +-
 docs/kbase/locking-sanlock.rst     |   2 +-
 docs/kbase/memorydevices.rst       |   2 +-
 docs/kbase/s390_protected_virt.rst |   2 +-
 docs/kbase/tlscerts.rst            |   8 +-
 docs/manpages/virsh.rst            |   8 +-
 docs/meson.build                   |  11 +
 docs/page.xsl                      |   2 +-
 docs/remote.rst                    |   4 +-
 docs/storage.rst                   |   6 +-
 docs/uri.rst                       |   4 +-
 scripts/check-html-references.py   | 153 ++++++++++++
 scripts/hvsupport.py               |   2 +-
 scripts/meson.build                |   1 +
 34 files changed, 402 insertions(+), 294 deletions(-)
 create mode 100755 scripts/check-html-references.py

-- 
2.35.3

On a Tuesday in 2022, Peter Krempa wrote:
>First 50 patches remove the use of raw HTML passthrough in
>formatdomain.rst, which is the only outstanding place which still does.
>

Is cleaning those up worth breaking links from external sites which
use the old anchors? I thought that was the only reason we left them
there.

Jano

>Most of the work was done by a ad-hoc bash script, but manual  tweaks
>were needed. Since this series also contains a test script which
>validates linking I'm not going to publish the conversion script.
>
>The rest of the series then cleans up pre-existing broken links and adds
>the aforementioned checker script.
>
>One more change is to prevent the use of external references in RST to
>refer to the same file. All usage was converted to local references and
>a syntax check was added.
>
>One slight drawback of the checker script is that it works on generated
>HTML files and thus the error message contains the output file name and
>not the source RST document.

On Tue, May 31, 2022 at 17:26:34 +0200, Ján Tomko wrote:
> On a Tuesday in 2022, Peter Krempa wrote:
> > First 50 patches remove the use of raw HTML passthrough in
> > formatdomain.rst, which is the only outstanding place which still does.
> > 
> 
> Is cleaning those up worth breaking links from external sites which
> use the old anchors? I thought that was the only reason we left them
> there.

Well, the main reason they were added originally was because it also
prevented us from having to convert all other documents we have locally
and allowed a mostly automated conversion.

For all other documents which didn't have so many internal cross-links
we already converted the links to the new names when doing the
conversion to RST

The external links case was certainly one of the selling points at that
time, but IMO the value of it decreased over the last almost 2 years
since the document was converted as all new links obtained from the
document are of the new format.

My stance (obviously since I posted the patches) is that since it's
inevitable that the links will break at some point and we had a good
enough intermediate period so we should just get over it and use what's
generated.

On a Tuesday in 2022, Peter Krempa wrote:
>On Tue, May 31, 2022 at 17:26:34 +0200, Ján Tomko wrote:
>> On a Tuesday in 2022, Peter Krempa wrote:
>> > First 50 patches remove the use of raw HTML passthrough in
>> > formatdomain.rst, which is the only outstanding place which still does.
>> >
>>
>> Is cleaning those up worth breaking links from external sites which
>> use the old anchors? I thought that was the only reason we left them
>> there.
>
>Well, the main reason they were added originally was because it also
>prevented us from having to convert all other documents we have locally
>and allowed a mostly automated conversion.
>
>For all other documents which didn't have so many internal cross-links
>we already converted the links to the new names when doing the
>conversion to RST
>
>The external links case was certainly one of the selling points at that
>time, but IMO the value of it decreased over the last almost 2 years
>since the document was converted as all new links obtained from the
>document are of the new format.
>
>My stance (obviously since I posted the patches) is that since it's
>inevitable that the links will break at some point and we had a good
>enough intermediate period so we should just get over it and use what's
>generated.
>

Series:
Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano