From 31526d4c26e924578cc13e5f1fce7c6907a256e3 Mon Sep 17 00:00:00 2001 From: chenxing Date: Fri, 14 Jun 2019 17:00:14 +0800 Subject: [PATCH] doc: Start using openstackdoctheme's extlink extension This ensures we have version-specific references to other projects [1]. Note that this doesn't mean the URLs are actually valid - we need to do more work (linkcheck?) here, but it's an improvement nonetheless. [1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper Change-Id: I118e4d211617c5df66ff04dc04e308a1d2fc67ad --- doc/source/conf.py | 16 +++++++++++++++- doc/source/contributor/ptl-guide.rst | 4 ++-- doc/source/contributor/release-management.rst | 3 +-- doc/source/contributor/running-tests.rst | 5 ++--- doc/source/contributor/vagrant-dev-env.rst | 6 ++---- doc/source/reference/bare-metal/ironic-guide.rst | 4 ++-- doc/source/reference/compute/hyperv-guide.rst | 4 ++-- doc/source/reference/compute/vmware-guide.rst | 4 ++-- doc/source/reference/compute/xenserver-guide.rst | 11 ++++------- .../deployment-and-bootstrapping/bifrost.rst | 4 ++-- .../reference/networking/designate-guide.rst | 3 +-- .../reference/networking/neutron-extensions.rst | 6 +++--- doc/source/reference/networking/sriov.rst | 8 ++++---- .../reference/shared-services/glance-guide.rst | 4 ++-- .../reference/shared-services/keystone-guide.rst | 5 ++--- .../reference/storage/cinder-guide-hnas.rst | 4 ++-- .../reference/storage/cinder-guide-quobyte.rst | 4 ++-- .../reference/storage/external-ceph-guide.rst | 4 ++-- doc/source/reference/storage/manila-guide.rst | 3 +-- .../reference/storage/manila-hnas-guide.rst | 7 +++---- doc/source/reference/storage/swift-guide.rst | 10 +++++----- doc/source/user/quickstart.rst | 15 ++++++++------- specs/containerize-openstack.rst | 3 +-- 23 files changed, 70 insertions(+), 67 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 67fb9971c4..f30ac88ea7 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. +from kolla_ansible.version import version_info as kolla_version import os import sys @@ -44,7 +45,6 @@ copyright = u'2013, OpenStack Foundation' # built documents. # # The short X.Y version. -from kolla_ansible.version import version_info as kolla_version # The full version, including alpha/beta/rc tags. release = kolla_version.version_string_with_vcs() # The short X.Y version. @@ -89,5 +89,19 @@ repository_name = 'openstack/kolla-ansible' bug_project = 'kolla-ansible' bug_tag = '' openstack_projects = [ + 'bifrost', + 'cinder', + 'designate', + 'glance', + 'ironic', + 'keystone', + 'kolla', 'kolla-ansible', + 'manila', + 'networking-sfc', + 'neutron-vpnaas', + 'neutron', + 'nova', + 'oslotest', + 'swift', ] diff --git a/doc/source/contributor/ptl-guide.rst b/doc/source/contributor/ptl-guide.rst index 115874f93d..34c94f4581 100644 --- a/doc/source/contributor/ptl-guide.rst +++ b/doc/source/contributor/ptl-guide.rst @@ -2,5 +2,5 @@ PTL Guide ========= -The Kolla PTL is also PTL for Kolla Ansible. See the `Kolla PTL guide -`__. +The Kolla PTL is also PTL for Kolla Ansible. See the +:kolla-doc:`Kolla PTL guide `. diff --git a/doc/source/contributor/release-management.rst b/doc/source/contributor/release-management.rst index 17c82181ae..e3a93c275f 100644 --- a/doc/source/contributor/release-management.rst +++ b/doc/source/contributor/release-management.rst @@ -3,5 +3,4 @@ Release Management ================== Release management for Kolla Ansible is very much linked to that of Kolla. See -`Kolla release management -`__. +:kolla-doc:`Kolla release management `. diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst index d16c779ebc..bf9481a2f5 100644 --- a/doc/source/contributor/running-tests.rst +++ b/doc/source/contributor/running-tests.rst @@ -98,6 +98,5 @@ Then run ``tox`` with the debug environment as one of the following: tox -e debug tox -e debug test_file_name.TestClass.test_name -For more information, see the `oslotest documentation -`_. - +For more information, see the :oslotest-doc:`oslotest documentation +`. diff --git a/doc/source/contributor/vagrant-dev-env.rst b/doc/source/contributor/vagrant-dev-env.rst index 0da089dd41..50be3f4f1e 100644 --- a/doc/source/contributor/vagrant-dev-env.rst +++ b/doc/source/contributor/vagrant-dev-env.rst @@ -1,5 +1,3 @@ -.. vagrant-dev-env: - ==================================== Development Environment with Vagrant ==================================== @@ -203,8 +201,8 @@ Once logged on the **operator** VM call the ``kolla-build`` utility: kolla-build -``kolla-build`` accept arguments as documented in `Building Container Images -`_. +``kolla-build`` accept arguments as documented in +:kolla-doc:`Building Container Images `. It builds Docker images and pushes them to the local registry if the **push** option is enabled (in Vagrant this is the default behaviour). diff --git a/doc/source/reference/bare-metal/ironic-guide.rst b/doc/source/reference/bare-metal/ironic-guide.rst index f4deafef32..5c00792534 100644 --- a/doc/source/reference/bare-metal/ironic-guide.rst +++ b/doc/source/reference/bare-metal/ironic-guide.rst @@ -186,8 +186,8 @@ requests may not be hitting various pieces of the process: Configuring the Web Console --------------------------- -Configuration based off upstream `Node web console -`__. +Configuration based off upstream :ironic-doc:`Node web console +`. Serial speed must be the same as the serial configuration in the BIOS settings. Default value: 115200bps, 8bit, non-parity.If you have different serial speed. diff --git a/doc/source/reference/compute/hyperv-guide.rst b/doc/source/reference/compute/hyperv-guide.rst index e101bdc038..ae4e218021 100644 --- a/doc/source/reference/compute/hyperv-guide.rst +++ b/doc/source/reference/compute/hyperv-guide.rst @@ -165,5 +165,5 @@ OpenStack HyperV services can be inspected and managed from PowerShell: PS C:\> Restart-Service neutron-hyperv-agent For more information on OpenStack HyperV, see -`Hyper-V virtualization platform -`__. +:nova-doc:`Hyper-V virtualization platform +`. diff --git a/doc/source/reference/compute/vmware-guide.rst b/doc/source/reference/compute/vmware-guide.rst index 4a8e9725d5..78c82a8e7c 100644 --- a/doc/source/reference/compute/vmware-guide.rst +++ b/doc/source/reference/compute/vmware-guide.rst @@ -269,6 +269,6 @@ Then you should start :command:`kolla-ansible` deployment normally as KVM/QEMU deployment. For more information on OpenStack vSphere, see -`VMware vSphere -`__, +:nova-doc:`VMware vSphere +`, `VMware-NSX package `_. diff --git a/doc/source/reference/compute/xenserver-guide.rst b/doc/source/reference/compute/xenserver-guide.rst index 70d5ac8708..27aaf0a40d 100644 --- a/doc/source/reference/compute/xenserver-guide.rst +++ b/doc/source/reference/compute/xenserver-guide.rst @@ -85,18 +85,15 @@ You also need set the password for xenserver_username in xenserver_password: "root_password" -Then you can start kolla-ansible deployment just following the general -deployment instructions [`Quick Start`_]. +Then you can start kolla-ansible deployment just following the +:doc:`/user/quickstart`. References ========== -For more information on XenAPI OpenStack, see: - -XenAPI OpenStack: https://docs.openstack.org/nova/latest/admin/configuration/hypervisor-xen-api.html +For more information on XenAPI OpenStack, see +:nova-doc:`XenAPI OpenStack ` .. _RDO repos: https://www.rdoproject.org/what/repos/ .. _XenServer documents: https://docs.citrix.com/en-us/xenserver/current-release.html - -.. _Quick Start: https://docs.openstack.org/kolla-ansible/latest/user/quickstart.html diff --git a/doc/source/reference/deployment-and-bootstrapping/bifrost.rst b/doc/source/reference/deployment-and-bootstrapping/bifrost.rst index 2385199fed..b26611b1a0 100644 --- a/doc/source/reference/deployment-and-bootstrapping/bifrost.rst +++ b/doc/source/reference/deployment-and-bootstrapping/bifrost.rst @@ -458,9 +458,9 @@ done remotely with :command:`ipmitool` and Serial Over LAN. For example References ~~~~~~~~~~ -* `Bifrost documentation `__ +* :bifrost-doc:`Bifrost documentation <>` -* `Bifrost troubleshooting guide `__ +* :bifrost-doc:`Bifrost troubleshooting guide ` * `Bifrost code repository `__ diff --git a/doc/source/reference/networking/designate-guide.rst b/doc/source/reference/networking/designate-guide.rst index e9d1903c9c..fab6796046 100644 --- a/doc/source/reference/networking/designate-guide.rst +++ b/doc/source/reference/networking/designate-guide.rst @@ -77,8 +77,7 @@ Configure Designate options in ``/etc/kolla/passwords.yml`` designate_infoblox_auth_password: "password" For more information about how the Infoblox backend works, see -`Infoblox backend -`__. +:designate-doc:`Infoblox backend `. Neutron and Nova Integration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/networking/neutron-extensions.rst b/doc/source/reference/networking/neutron-extensions.rst index 6b1d8b6ce8..f557bf5354 100644 --- a/doc/source/reference/networking/neutron-extensions.rst +++ b/doc/source/reference/networking/neutron-extensions.rst @@ -20,8 +20,8 @@ Verification ------------ For setting up a testbed environment and creating a port chain, please refer -to `networking-sfc documentation -`__. +to :networking-sfc-doc:`networking-sfc documentation +`. Neutron VPNaaS (VPN-as-a-Service) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -76,5 +76,5 @@ Two VMs can now be booted, one on vpn_east, the other on vpn_west, and encrypted ping packets observed being sent from one to the other. For more information on this and VPNaaS in Neutron refer to the -`Neutron VPNaaS Testing `__ +:neutron-vpnaas-doc:`Neutron VPNaaS Testing ` and the `OpenStack wiki `_. diff --git a/doc/source/reference/networking/sriov.rst b/doc/source/reference/networking/sriov.rst index 7cf6d8cb0a..01653b347e 100644 --- a/doc/source/reference/networking/sriov.rst +++ b/doc/source/reference/networking/sriov.rst @@ -165,8 +165,8 @@ dmesg on the compute node where the instance was placed. [ 2896.850028] ixgbe 0000:05:00.0: Setting VLAN 1000, QOS 0x0 on VF 3 [ 2897.403367] vfio-pci 0000:05:10.4: enabling device (0000 -> 0002) -For more information see `OpenStack SRIOV documentation -`_. +For more information see :neutron-doc:`OpenStack SRIOV documentation +`. Nova SRIOV ~~~~~~~~~~ @@ -222,5 +222,5 @@ Start a new instance using the flavor: Verify VF devices were created and the instance starts successfully as in the Neutron SRIOV case. -For more information see `OpenStack PCI passthrough documentation -`_. +For more information see :nova-doc:`OpenStack PCI passthrough documentation +`. diff --git a/doc/source/reference/shared-services/glance-guide.rst b/doc/source/reference/shared-services/glance-guide.rst index 6a7bce200e..2b3dae4e1e 100644 --- a/doc/source/reference/shared-services/glance-guide.rst +++ b/doc/source/reference/shared-services/glance-guide.rst @@ -144,5 +144,5 @@ Glance cache is disabled by default, it can be enabled by: Glance caches are not cleaned up automatically, the glance team recommends to use a cron service to regularly clean cached images. In the future kolla will -deploy a cron container to manage such clean ups. Please refer to `Glance -image cache `__. +deploy a cron container to manage such clean ups. Please refer to +:glance-doc:`Glance image cache `. diff --git a/doc/source/reference/shared-services/keystone-guide.rst b/doc/source/reference/shared-services/keystone-guide.rst index b15e793ee8..2012b868f6 100644 --- a/doc/source/reference/shared-services/keystone-guide.rst +++ b/doc/source/reference/shared-services/keystone-guide.rst @@ -38,6 +38,5 @@ a buffer key - three in total. If the rotation interval is set lower than the sum of the token expiry and token allow expired window, more active keys will be configured in Keystone as necessary. -Further infomation on Fernet tokens is available in the `Keystone -documentation -`__. +Further infomation on Fernet tokens is available in the :keystone-doc:`Keystone +documentation `. diff --git a/doc/source/reference/storage/cinder-guide-hnas.rst b/doc/source/reference/storage/cinder-guide-hnas.rst index e710c4c1b8..4a36d6750e 100644 --- a/doc/source/reference/storage/cinder-guide-hnas.rst +++ b/doc/source/reference/storage/cinder-guide-hnas.rst @@ -237,8 +237,8 @@ Verify Operation. +--------------------------------------+---------------+----------------+------+-------------------------------------------+ For more information about how to manage volumes, see the -`Manage volumes -`__. +:cinder-doc:`Manage volumes +`. For more information about how HNAS driver works, see `Hitachi NAS Platform iSCSI and NFS drives for OpenStack diff --git a/doc/source/reference/storage/cinder-guide-quobyte.rst b/doc/source/reference/storage/cinder-guide-quobyte.rst index 575239eb47..ce38223fa6 100644 --- a/doc/source/reference/storage/cinder-guide-quobyte.rst +++ b/doc/source/reference/storage/cinder-guide-quobyte.rst @@ -23,7 +23,7 @@ registry and the Quobyte volume respectively. Since ``Quobyte`` is proprietary software that requires a license, the use of this backend requires the ``Quobyte`` Client software package to be installed in the ``cinder-volume`` and ``nova-compute`` containers. To do this follow the -steps outlined in the `kolla image building guide -`__, +steps outlined in the :kolla-doc:`Building Container Images +`, particularly the ``Package Customisation`` and ``Custom Repos`` sections. The repository information is available in the ``Quobyte`` customer portal. diff --git a/doc/source/reference/storage/external-ceph-guide.rst b/doc/source/reference/storage/external-ceph-guide.rst index 2e44f3d4eb..8eda754229 100644 --- a/doc/source/reference/storage/external-ceph-guide.rst +++ b/doc/source/reference/storage/external-ceph-guide.rst @@ -282,5 +282,5 @@ in Ceph) into the same directory, for example: For more details on the rest of the Manila setup, such as creating the share type ``default_share_type``, please see :doc:`Manila in Kolla `. -For more details on the CephFS Native driver, please see `CephFS driver -`__. +For more details on the CephFS Native driver, please see +:manila-doc:`CephFS driver `. diff --git a/doc/source/reference/storage/manila-guide.rst b/doc/source/reference/storage/manila-guide.rst index 5a9dec4226..3183f590db 100644 --- a/doc/source/reference/storage/manila-guide.rst +++ b/doc/source/reference/storage/manila-guide.rst @@ -361,5 +361,4 @@ Use the :command:`manila migration-complete shareID` command to complete share migration process. For more information about how to manage shares, see the -`Manage shares -`__. +:manila-doc:`Manage shares `. diff --git a/doc/source/reference/storage/manila-hnas-guide.rst b/doc/source/reference/storage/manila-hnas-guide.rst index f4bf452367..33124a1747 100644 --- a/doc/source/reference/storage/manila-hnas-guide.rst +++ b/doc/source/reference/storage/manila-hnas-guide.rst @@ -323,9 +323,8 @@ Modify the file ``/etc/kolla/config/manila-share.conf`` and add the contents: hitachi_hnas_file_system_name = FS-Manila2 For more information about how to manage shares, see the -`Manage shares -`__. +:manila-doc:`Manage shares `. For more information about how HNAS driver works, see -`Hitachi NAS Platform File Services Driver for OpenStack -`__. +:manila-doc:`Hitachi NAS Platform File Services Driver for OpenStack +`. diff --git a/doc/source/reference/storage/swift-guide.rst b/doc/source/reference/storage/swift-guide.rst index 3b53783b75..ef9257afdc 100644 --- a/doc/source/reference/storage/swift-guide.rst +++ b/doc/source/reference/storage/swift-guide.rst @@ -94,9 +94,9 @@ table** example listed above. Please modify accordingly if your setup is different. If using a separate replication network it is necessary to add the replication -network IP addresses to the rings. See the `Swift documentation -`__ -for details on how to do that. +network IP addresses to the rings. See the :swift-doc:`Swift documentation +` for details on +how to do that. Prepare for Rings generating ---------------------------- @@ -203,8 +203,8 @@ To rebalance the ring files: /etc/kolla/config/swift/${ring}.builder rebalance; done -For more information, see `the Swift documentation -`__. +For more information, see :swift-doc:`the Swift documentation +`. Deploying ~~~~~~~~~ diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index 0d2d58487f..78b69e030d 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -367,8 +367,8 @@ There are a few options that are required to deploy Kolla-Ansible: User has to specify images that are going to be used for our deployment. In this guide `DockerHub `__ provided pre-built images are going to be used. To learn more about building - mechanism, please refer `image building documentation - `_. + mechanism, please refer :kolla-doc:`Building Container Images + `. Kolla provides choice of several Linux distributions in containers: @@ -444,8 +444,9 @@ There are a few options that are required to deploy Kolla-Ansible: neutron_external_interface: "eth1" - To learn more about network configuration, refer `Network overview - `_. + To learn more about network configuration, refer + :kolla-ansible-doc:`Network overview + `. Next we need to provide floating IP for management traffic. This IP will be managed by keepalived to provide high availability, and should be set to be @@ -470,8 +471,8 @@ There are a few options that are required to deploy Kolla-Ansible: `a list of available services `_. For more information about service configuration, Please refer to the - `Services Reference Guide - `_. + :kolla-ansible-doc:`Services Reference Guide + `. * Virtual environment @@ -535,7 +536,7 @@ accordingly. When this playbook finishes, OpenStack should be up, running and functional! If error occurs during execution, refer to -`troubleshooting guide `_. +:kolla-ansible-doc:`troubleshooting guide `. Using OpenStack ~~~~~~~~~~~~~~~ diff --git a/specs/containerize-openstack.rst b/specs/containerize-openstack.rst index f32635b3ef..9acdc99279 100644 --- a/specs/containerize-openstack.rst +++ b/specs/containerize-openstack.rst @@ -194,8 +194,7 @@ A different motive for not using EXPOSE is the 20 microsecond penalty applied to every packet forwarded and returned by docker-proxy. If EXPOSE functionality is desired, it can be added back by referencing the default list of OpenStack ports to each Dockerfile: - - https://docs.openstack.org/liberty/config-reference/content/firewalls-default-ports.html +`Firewalls and default ports `__. We will use the docker flag --restart=always to provide some measure of high availability for the individual containers and ensure they operate