From d2a9a6380a0919febb066bce472653500b942dd2 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 16 Sep 2022 22:34:48 -0400 Subject: [PATCH] Add linkchecking Enable the built-in Sphinx 'linkcheck' builder and fix initial findings. Add this as an opportunistic build target only. The process is long, and false positives are common (mostly anchor-related for some reason). There is also already a third-party company-wide service in place. This builder however will lead to better link hygiene as it is stricter (mostly for anchors). It also records all redirects, which should eventually be replaced by proper links. Change-Id: Ibed74b9f820c17a5984a78f4f61153e0499453fa --- doc/source/admin/deferred-events.rst | 12 ++++++------ doc/source/admin/networking/ovn/hardware-offload.rst | 4 ++-- doc/source/admin/policy-overrides.rst | 2 +- doc/source/admin/storage/ceph-rbd-mirror.rst | 2 +- doc/source/conf.py | 6 ++++++ doc/source/release-notes/1907.rst | 4 +++- doc/source/release-notes/2005.rst | 5 ++--- doc/source/release-notes/2010.rst | 4 +--- doc/source/release-notes/2101.rst | 7 +++---- doc/source/release-notes/2104.rst | 2 +- tox.ini | 4 ++++ 11 files changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/source/admin/deferred-events.rst b/doc/source/admin/deferred-events.rst index 24a34962..800e438b 100644 --- a/doc/source/admin/deferred-events.rst +++ b/doc/source/admin/deferred-events.rst @@ -155,9 +155,9 @@ action: .. LINKS .. CHARMS -.. _neutron-gateway: https://opendev.org/openstack/charm-neutron-gateway/src/branch/master/README.md#user-content-deferred-restarts -.. _neutron-openvswitch: https://opendev.org/openstack/charm-neutron-openvswitch/src/branch/master/README.md#user-content-deferred-restarts -.. _ovn-central: https://opendev.org/x/charm-ovn-central/src/branch/master/README.md#user-content-deferred-restarts -.. _ovn-chassis: https://opendev.org/x/charm-ovn-chassis/src/branch/master/README.md#user-content-deferred-restarts -.. _ovn-dedicated-chassis: https://opendev.org/x/charm-ovn-dedicated-chassis/src/branch/master/README.md#user-content-deferred-restarts -.. _rabbitmq-server: https://opendev.org/openstack/charm-rabbitmq-server/src/branch/master/README.md#user-content-deferred-restarts +.. _neutron-gateway: https://opendev.org/openstack/charm-neutron-gateway/src/branch/master/README.md#deferred-service-events +.. _neutron-openvswitch: https://opendev.org/openstack/charm-neutron-openvswitch/src/branch/master/README.md#deferred-service-events +.. _ovn-central: https://opendev.org/x/charm-ovn-central/src/branch/master/README.md#deferred-service-events +.. _ovn-chassis: https://opendev.org/x/charm-ovn-chassis/src/branch/master/README.md#deferred-service-events +.. _ovn-dedicated-chassis: https://opendev.org/x/charm-ovn-dedicated-chassis/src/branch/master/README.md#deferred-service-events +.. _rabbitmq-server: https://opendev.org/openstack/charm-rabbitmq-server/src/branch/master/README.md#deferred-service-events diff --git a/doc/source/admin/networking/ovn/hardware-offload.rst b/doc/source/admin/networking/ovn/hardware-offload.rst index 2dcf523f..09a65e4d 100644 --- a/doc/source/admin/networking/ovn/hardware-offload.rst +++ b/doc/source/admin/networking/ovn/hardware-offload.rst @@ -153,5 +153,5 @@ the `data path control tools`_ to monitor offloaded flows. recirc_id(0),in_port(7),eth(src=fa:16:3e:b9:db:c8,dst=fa:16:3e:b2:20:82),eth_type(0x0800),ipv4(dst=10.42.0.16/255.255.255.240,proto=6,tos=0/0x3,frag=no),tcp_flags(psh|ack), packets:3873, bytes:31053714, used:0.590s, actions:set(tunnel(tun_id=0x4,dst=10.6.12.8,ttl=64,tp_dst=6081,key6(bad key length 1, expected 0)(01)geneve({class=0x102,type=0x80,len=4,0x70006}),flags(key))),2 .. LINKS -.. _traffic control monitor: http://manpages.ubuntu.com/manpages/focal/man8/tc.8.html#monitor -.. _data path control tools: http://manpages.ubuntu.com/manpages/focal/man8/ovs-dpctl.8.html +.. _traffic control monitor: https://manpages.ubuntu.com/manpages/focal/man8/tc.8.html +.. _data path control tools: https://manpages.ubuntu.com/manpages/focal/man8/ovs-dpctl.8.html diff --git a/doc/source/admin/policy-overrides.rst b/doc/source/admin/policy-overrides.rst index 86de6464..7b828e1c 100644 --- a/doc/source/admin/policy-overrides.rst +++ b/doc/source/admin/policy-overrides.rst @@ -299,7 +299,7 @@ See the upstream documentation on `Show Server Details`_. .. _policy.json: https://docs.openstack.org/oslo.policy/latest/admin/policy-json-file.html .. _Nova API: https://docs.openstack.org/nova/latest/configuration/policy.html .. _Show Server Details: https://docs.openstack.org/api-ref/compute/?expanded=show-server-details-detail#show-server-details -.. _Application resource: https://juju.is/docs/sdk/resources#heading--application-resources +.. _Application resource: https://juju.is/docs/sdk/resources .. CHARMS .. _cinder: https://opendev.org/openstack/charm-cinder/src/branch/master/README.md#user-content-policy-overrides diff --git a/doc/source/admin/storage/ceph-rbd-mirror.rst b/doc/source/admin/storage/ceph-rbd-mirror.rst index d1ef9057..b24a6733 100644 --- a/doc/source/admin/storage/ceph-rbd-mirror.rst +++ b/doc/source/admin/storage/ceph-rbd-mirror.rst @@ -354,4 +354,4 @@ Here, we make site 'a' be the primary by demoting site 'b' and promoting site .. _charm's documentation: https://opendev.org/openstack/charm-ceph-rbd-mirror/src/branch/master/src/README.md .. _RBD mirroring: https://docs.ceph.com/en/latest/rbd/rbd-mirroring .. _Geographical Redundancy with rbd-mirror: https://youtu.be/ZifNGprBUTA -.. _Cross model relations: https://juju.is/docs/olm/cross-model-relations +.. _Cross model relations: https://juju.is/docs/olm/manage-cross-model-relations diff --git a/doc/source/conf.py b/doc/source/conf.py index 395f3927..67bd53f0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -57,6 +57,12 @@ spelling_word_list_filename = [ '_spelling/dubious_words.txt' ] +# Linkchecker +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder +#linkcheck_anchors=False # disable anchor checks to reduce false positives +linkcheck_retries=2 # juju.is/docs has trouble - probably Discourse related +linkcheck_timeout=8 # ditto + # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] diff --git a/doc/source/release-notes/1907.rst b/doc/source/release-notes/1907.rst index ead6962f..5def3a6b 100644 --- a/doc/source/release-notes/1907.rst +++ b/doc/source/release-notes/1907.rst @@ -131,7 +131,9 @@ a nova-compute unit will be faster than before and the nova-cloud-controller upgrade-charm hook will be significantly improved for large deployments. For more information about the cache-known-hosts option refer to the -`charm documentation `__. +`charm-config-cache-known-hosts +`__ +section of the nova-cloud-controller charm README. Preview Charm Features ====================== diff --git a/doc/source/release-notes/2005.rst b/doc/source/release-notes/2005.rst index d2cf0081..4980969e 100644 --- a/doc/source/release-notes/2005.rst +++ b/doc/source/release-notes/2005.rst @@ -282,8 +282,8 @@ A more complex example bundle is available in `OpenStack bundles Focal Ussuri`_. In Ubuntu 20.04 LTS (Focal) percona-cluster will no longer be available. The -migration process is documented in the `Specific series upgrade procedures`_ -page in the `OpenStack Charms Deployment Guide`_. +migration process is documented on the +:doc:`../project/procedures/percona-series-upgrade-to-focal` page. Masakari charms ~~~~~~~~~~~~~~~ @@ -615,7 +615,6 @@ Please see the `OpenStack Charm Guide`_ for current information. .. _Neutron documentation: https://docs.openstack.org/neutron/latest/admin/config-fip-port-forwardings.html .. _placement API: https://docs.openstack.org/placement/ussuri/ .. _HA with pause/resume: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-upgrade-openstack.html#ha-with-pause-resume -.. _Specific series upgrade procedures: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-series-upgrade-specific-procedures.html#percona-series-upgrade-to-focal .. _Swift Auth system: https://docs.openstack.org/swift/latest/overview_auth.html .. _Swift Global Cluster: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-swift-gc.html .. _Toward Convergence of ML2+OVS+DVR and OVN: http://specs.openstack.org/openstack/neutron-specs/specs/ussuri/ml2ovs-ovn-convergence.html diff --git a/doc/source/release-notes/2010.rst b/doc/source/release-notes/2010.rst index 8fd487e8..8fb937e8 100644 --- a/doc/source/release-notes/2010.rst +++ b/doc/source/release-notes/2010.rst @@ -83,8 +83,7 @@ Action based migration from Neutron ML2+OVS to ML2+OVN New actions have been introduced to enable migration of a Neutron ML2+OVS based deployment to ML2+OVN. -Please refer to the `Migration from Neutron ML2+OVS to ML2+OVN section of the -OVN`_ appendix in the `OpenStack Charms Deployment Guide`_ for more +Please refer to the :doc:`../project/procedures/ovn-migration` page for more information. Ceph BlueStore compression support @@ -320,7 +319,6 @@ Deployment Guide`_ for more details. .. _OpenStack upgrades: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-upgrade-openstack.html .. _Open vSwitch Integration Guide for Centralized Control: https://docs.openvswitch.org/en/latest/topics/integration/ .. _vault charm: https://charmhub.io/vault -.. _Migration from Neutron ML2+OVS to ML2+OVN section of the OVN: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ovn.html#migration-from-neutron-ml2-ovs-to-ml2-ovn .. _Octavia deprecation notes for Victoria: https://docs.openstack.org/releasenotes/octavia/victoria.html#deprecation-notes .. COMMITS diff --git a/doc/source/release-notes/2101.rst b/doc/source/release-notes/2101.rst index 864e6ffd..9ae75f43 100644 --- a/doc/source/release-notes/2101.rst +++ b/doc/source/release-notes/2101.rst @@ -180,9 +180,9 @@ When performed on Ubuntu 20.10 (Groovy), the procedure for migrating an OpenStack cloud from ML2+OVS to ML2+OVN may require an extra step due to Open vSwitch bug `LP #1852221`_. -Following the procedure in the `Migration from Neutron ML2+OVS to ML2+OVN`_ -section of the deploy guide, the workaround is to restart the `ovs-vswitchd` -service after resuming the ovn-chassis charm in step 15: +Following the procedure on the :doc:`../project/procedures/ovn-migration` page. +The workaround is to restart the `ovs-vswitchd` service after resuming the +ovn-chassis charm in step 15: .. code-block:: none @@ -231,7 +231,6 @@ in the `OpenStack Charms Deployment Guide`_. .. _Cinder-Ceph replication development notes: https://github.com/ionutbalutoiu/cinder-ceph-replication .. _MicroStack: https://microstack.run .. _openstack-on-lxd: https://github.com/openstack-charmers/openstack-on-lxd -.. _Migration from Neutron ML2+OVS to ML2+OVN: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ovn.html#migration-from-neutron-ml2-ovs-to-ml2-ovn .. COMMITS diff --git a/doc/source/release-notes/2104.rst b/doc/source/release-notes/2104.rst index 36922782..55773b91 100644 --- a/doc/source/release-notes/2104.rst +++ b/doc/source/release-notes/2104.rst @@ -275,7 +275,7 @@ in the `OpenStack Charms Deployment Guide`_. .. _OpenStack Charm Guide: https://docs.openstack.org/charm-guide/latest/ .. _Upgrades overview: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/upgrade-overview.html .. _vault charm: https://opendev.org/openstack/charm-vault/src/branch/master/src/README.md#unseal-vault -.. _hacluster charm: https://opendev.org/openstack/charm-hacluster/src/branch/master/README.md#update-ring-action +.. _hacluster charm: https://opendev.org/openstack/charm-hacluster/src/branch/master/README.md .. _Migration from Neutron ML2+OVS to ML2+OVN: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ovn.html#migration-from-neutron-ml2-ovs-to-ml2-ovn .. _What is STONITH?: https://clusterlabs.org/pacemaker/doc/en-US/Pacemaker/1.1/html/Clusters_from_Scratch/ch08.html .. _nova-compute charm: https://opendev.org/openstack/charm-nova-compute/src/branch/master/README.md#cloud-downscaling diff --git a/tox.ini b/tox.ini index 360ed136..8fc8e66c 100644 --- a/tox.ini +++ b/tox.ini @@ -11,6 +11,10 @@ deps = -r{toxinidir}/requirements.txt [testenv:venv] commands = {posargs} +[testenv:linkcheck] +# redirects and broken links are recorded in doc/build/html/output.txt +commands = sphinx-build -j auto -d doc/build/doctrees -b linkcheck doc/source doc/build/html + [testenv:spelling] commands = sphinx-build -j auto -W -d doc/build/doctrees -b html -b spelling doc/source doc/build/html