Fix citation references (Sphinx 1.6.x compatibility)

Sphinx 1.6.x gained a cross-reference check warning that caused
the build to fail in "tox -e docs" environment. Removing underscores
from the citation reference identifier ensures that the cross references
are properly detected. Similarly missing references to footnotes are
now a warning (which is upgraded to an error in the docs tox
environment) so adjust references where it makes sense and is needed.

Closes-Bug: #1695127
Change-Id: I7e55dcf910e0ba6dd85b565db8cb1ecbdd39634a

specs/juno/approved/libvirt-sheepdog-backed-instances.rst

@@ -149,14 +149,14 @@ Testing
 
 Devstack integration is required before tempest can run functional
 tests against the Sheepdog drivers for Nova, Glance and Cinder. A patch
-has been proposed which would use Sheepdog for each service. [2]
+has been proposed which would use Sheepdog for each service. [2]_
 
 This, I think, would result in many functional tests of the Sheepdog
 drivers via the Tempest tests. However, a Jenkins job would need
 to be defined and VMs would need to be provisioned to run the jobs.
 It is not clear if openstack-infra is willing or capable of committing
 to a proliferation of CI test runs. There is a Juno Summit scheduled for
-this. [3]
+this. [3]_
 
 
 Documentation Impact

specs/juno/implemented/pci-passthrough-sriov.rst

@@ -16,7 +16,7 @@ Problem description
 ===================
 Right now it is possible to boot VM with general purpose PCI device passthrough
 by means of libvirt's managed hostdev device definition in the domain XML. A
-guide to use it can be found in [GPP_WIKI]_. However, it's not possible to
+guide to use it can be found in [GPPWIKI]_. However, it's not possible to
 request access to virtual network via SR-IOV NICs. Nova enhancments are
 required to support SR-IOV networking with Neutron.
 
@@ -35,10 +35,10 @@ VF. Using a macvtap device makes live migration with SR-IOV possible.
 
 In the Icehouse release, a couple of blueprints from neutron side were approved
 and their associated patches were committed that enable the interactions
-between nova and neutron for SR-IOV networking. Refer to [VIF_DETA]_ and
+between nova and neutron for SR-IOV networking. Refer to [VIFDETA]_ and
-[BIND_PRF]_ for details about them.
+[BINDPRF]_ for details about them.
 
-Another blueprint [VNIC_TYP]_ added the support in the neutron port API to
+Another blueprint [VNICTYP]_ added the support in the neutron port API to
 allow users to specify vnic-type when creating a neutron port. The currently
 supported vnic-types are:
 
@@ -78,7 +78,7 @@ virtual port (which is not a SR-IOV port).
 
 This specification will make use of the existing PCI passthrough
 implementation, and make a few enhancements to enable the above use cases.
-Therefore, the existing PCI passthrough support as documented by [GPP_WIKI]_
+Therefore, the existing PCI passthrough support as documented by [GPPWIKI]_
 works as it is for general-purpose PCI passthrough.
 
 Proposed change
@@ -272,7 +272,7 @@ nova neutronv2 and VIF
 Note that Nova network will not be enhanced to support SR-IOV. However, Nova
 modules that are responsible for interacting with neutron need to be enhanced.
 
-Refer to [BIND_PRF]_, [VIF_DETA]_, [VNIC_TYP]_ that has added the
+Refer to [BINDPRF]_, [VIFDETA]_, [VNICTYP]_ that has added the
 functionalities required to support SR-IOV ports in neutron. Accordingly, nova
 neutronv2 will be enhanced to work with them in support of SR-IOV ports.
 Particularly:
@@ -408,7 +408,7 @@ Documentation Impact
 
 References
 ==========
-.. [GPP_WIKI] `Generic PCI Passthrough WIKI <https://wiki.openstack.org/wiki/Pci_passthrough>`_
+.. [GPPWIKI] `Generic PCI Passthrough WIKI <https://wiki.openstack.org/wiki/Pci_passthrough>`_
-.. [VIF_DETA] `Extensible port attribute for plugin to provide details to VIF driver  <https://blueprints.launchpad.net/neutron/+spec/vif-details>`_
+.. [VIFDETA] `Extensible port attribute for plugin to provide details to VIF driver  <https://blueprints.launchpad.net/neutron/+spec/vif-details>`_
-.. [BIND_PRF] `Implement the binding:profile port attribute in ML2 <https://blueprints.launchpad.net/neutron/+spec/ml2-binding-profile>`_
+.. [BINDPRF] `Implement the binding:profile port attribute in ML2 <https://blueprints.launchpad.net/neutron/+spec/ml2-binding-profile>`_
-.. [VNIC_TYP] `Add support for vnic type request to be managed by ML3 mechanism drivers <https://blueprints.launchpad.net/neutron/+spec/ml2-request-vnic-type>`_
+.. [VNICTYP] `Add support for vnic type request to be managed by ML3 mechanism drivers <https://blueprints.launchpad.net/neutron/+spec/ml2-request-vnic-type>`_

specs/mitaka/approved/expose-quiesce-unquiesce-api.rst

@@ -242,13 +242,12 @@ createImage action).
 References
 ==========
 
-.. [1] nova-specs: 'Quiesce filesystems with QEMU guest agent during image
+nova-specs: 'Quiesce filesystems with QEMU guest agent during image snapshot':
-       snapshot':
+`<https://review.openstack.org/#/c/126966/>`_
-       https://review.openstack.org/#/c/126966/
 
-.. [2] 'quiesce' and 'unquiesce' methods for libvirt driver:
+'quiesce' and 'unquiesce' methods for libvirt driver:
-       https://blueprints.launchpad.net/nova/+spec/quiesced-image-snapshots-with-qemu-guest-agen/atomic/async
+`<https://blueprints.launchpad.net/nova/+spec/quiesced-image-snapshots-with-qemu-guest-agen/atomic/async>`_
 
-.. [3] a VNF (telecom application) should, be able to restore in another site
+a VNF (telecom application) should, be able to restore in another site
-       for catastrophic failures happened
+for catastrophic failures happened
-       https://git.opnfv.org/cgit/multisite/tree/multisite-vnf-gr-requirement.rst
+`<https://git.opnfv.org/cgit/multisite/tree/multisite-vnf-gr-requirement.rst>`_

specs/mitaka/implemented/sriov-physical-function-passthrough.rst

@@ -268,7 +268,6 @@ References
 
 .. [1] https://review.openstack.org/#/c/182242/
 .. [2] https://review.openstack.org/#/c/142094/
-.. [3] https://blueprints.launchpad.net/nova/+spec/pci-passthrough-whitelist-regex
 
 History
 =======

specs/newton/implemented/cells-aggregate-api-db.rst

@@ -21,7 +21,7 @@ Aggregates may be applied to compute nodes in multiple cells and are a global
 concept.
 
 Currently aggregates are stored in the cell database but to keep their global
-nature they must be migrated to the API database.
+nature they must be migrated to the API database [1]_.
 
 Use Cases
 ---------