From dd70d9244d5a8b8b91b3e5908b45bf5b7f6a8974 Mon Sep 17 00:00:00 2001 From: Zane Bitter Date: Wed, 22 Jan 2020 10:32:43 -0500 Subject: [PATCH] Docs: use extrefs to link to other projects' docs This feature of openstackdocstheme means that we'll always link to the corresponding branch of another project (i.e. latest links to latest, but train links to train, &c.) https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper Change-Id: If94115f87af3689413405f3283be7fb197fab058 --- doc/source/admin/auth-model.rst | 5 +- doc/source/admin/introduction.rst | 4 +- doc/source/admin/stack-domain-users.rst | 5 +- doc/source/conf.py | 13 +++++ doc/source/developing_guides/gmr.rst | 2 +- doc/source/getting_started/create_a_stack.rst | 9 ++-- doc/source/glossary.rst | 12 ++--- doc/source/index.rst | 3 +- doc/source/install/install-rdo.rst | 15 +++--- .../operating_guides/scale_deployment.rst | 12 ++--- doc/source/template_guide/multi-clouds.rst | 52 +++++++++---------- .../template_guide/software_deployment.rst | 12 ++--- 12 files changed, 74 insertions(+), 70 deletions(-) diff --git a/doc/source/admin/auth-model.rst b/doc/source/admin/auth-model.rst index 45effc556b..3c404e9719 100644 --- a/doc/source/admin/auth-model.rst +++ b/doc/source/admin/auth-model.rst @@ -77,7 +77,8 @@ which is consumed by *only* the trustee to obtain a such that the trustee has limited access to those roles delegated. In addition, the trustee has effective impersonation of the trustor user if it was selected when creating the trust. -For more information, see `Identity Management trusts`_. +For more information, see :keystone-doc:`Identity management trusts +`. Trusts authorization involves the following steps: @@ -146,5 +147,3 @@ defined, then all the trustor roles are delegated to trustee. The trustor delegated roles must be pre-configured in the OpenStack Identity service before using them in the Orchestration service. - -.. _Identity management trusts: https://docs.openstack.org/keystone/latest/admin/identity-use-trusts.html diff --git a/doc/source/admin/introduction.rst b/doc/source/admin/introduction.rst index 61187b9c59..a666734134 100644 --- a/doc/source/admin/introduction.rst +++ b/doc/source/admin/introduction.rst @@ -28,5 +28,5 @@ integrated with the OpenStack dashboard to perform stack functions through a web interface. For more information about using the Orchestration service through the -command line, see the `Heat Command-Line Interface reference -`_. +command line, see the :python-heatclient-doc:`Heat Command-Line Interface +reference <#openstackclient-command-line>`. diff --git a/doc/source/admin/stack-domain-users.rst b/doc/source/admin/stack-domain-users.rst index f5f043bc7e..fa869d943f 100644 --- a/doc/source/admin/stack-domain-users.rst +++ b/doc/source/admin/stack-domain-users.rst @@ -125,7 +125,8 @@ The following steps are run during stack creation: in the stack domain are still assigned the ``heat_stack_user`` role, so the API surface they can access is limited through the :file:`policy.json` file. - For more information, see `OpenStack Identity documentation`_. + For more information, see :keystone-doc:`OpenStack Identity documentation + <>`. #. When API requests are processed, the Orchestration service performs an internal lookup, and allows stack details for a given stack to be @@ -149,5 +150,3 @@ or:: The stack owner uses the former (via ``openstack stack resource metadata STACK RESOURCE``), and any agents in the instance use the latter. - -.. _OpenStack Identity documentation: https://docs.openstack.org/keystone/latest/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 3c2cfba4bd..47192e14ed 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -100,6 +100,19 @@ bug_tag = 'docs' todo_include_todos = True +# openstackdocstheme external link helper projects +openstack_projects = [ + 'devstack', + 'diskimage-builder', + 'keystone', + 'keystoneauth', + 'nova', + 'oslo.reports', + 'python-barbicanclient', + 'python-heatclient', + 'python-openstackclient', +] + # Add any paths that contain templates here, relative to this directory. templates_path = [] diff --git a/doc/source/developing_guides/gmr.rst b/doc/source/developing_guides/gmr.rst index f2daeaae87..26d1d41f7e 100644 --- a/doc/source/developing_guides/gmr.rst +++ b/doc/source/developing_guides/gmr.rst @@ -90,4 +90,4 @@ Extending the GMR As mentioned above, additional sections can be added to the GMR for a particular executable. For more information, see the documentation about -`oslo.reports `_ +:oslo.reports-doc:`oslo.reports <>`. diff --git a/doc/source/getting_started/create_a_stack.rst b/doc/source/getting_started/create_a_stack.rst index 8b8f03dac3..0d1576a922 100644 --- a/doc/source/getting_started/create_a_stack.rst +++ b/doc/source/getting_started/create_a_stack.rst @@ -118,8 +118,7 @@ Note: The list operation will show no running stack.:: $ openstack stack delete teststack $ openstack stack list -You can explore other heat commands by referring to the `Heat command reference -`_ for the -`OpenStack Command-Line Interface -`_; then read the -:ref:`template-guide` and start authoring your own templates. +You can explore other heat commands by referring to the +:python-heatclient-doc:`Heat command reference ` for the +:python-openstackclient-doc:`OpenStack Command-Line Interface <>`; then read +the :ref:`template-guide` and start authoring your own templates. diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index 304bc1b467..316a3c9dbf 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -57,10 +57,9 @@ Metadata service A Compute service that enables virtual machine instances to - retrieve instance-specific data. See `Metadata - service (OpenStack Administrator Guide)`_. - - .. _Metadata service (OpenStack Administrator Guide): https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service + retrieve instance-specific data. See :nova-doc:`Metadata + service (OpenStack Administrator Guide) + `. Multi-region A feature of Heat that supports deployment to multiple regions. @@ -162,10 +161,9 @@ User data A :term:`resource property` that contains a user-provided data blob. User data gets passed to `cloud-init`_ to automatically - configure instances at boot time. See also `User data (OpenStack - End User Guide)`_. + configure instances at boot time. See also :nova-doc:`User data + (OpenStack End User Guide) `. - .. _User data (OpenStack End User Guide): https://docs.openstack.org/nova/latest/user/user-data.html .. _cloud-init: https://cloudinit.readthedocs.io/ Wait condition diff --git a/doc/source/index.rst b/doc/source/index.rst index 0f87552949..956eaf32de 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -80,10 +80,9 @@ Using the Heat Service ---------------------- - `OpenStack Orchestration API v1 Reference`_ -- `Python and CLI client`_ +- :python-heatclient-doc:`Python and CLI client <>` .. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/ -.. _`Python and CLI client`: https://docs.openstack.org/python-heatclient/latest Developing Heat =============== diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst index 54072ed4aa..e5bfae0e79 100644 --- a/doc/source/install/install-rdo.rst +++ b/doc/source/install/install-rdo.rst @@ -74,14 +74,13 @@ requires additional information in the Identity service. .. note:: - If installing OpenStack manually following the `Keystone install - guide`_, the name of the services project is ``service`` as given - above. However, traditional methods of installing RDO (such as - PackStack and TripleO) use ``services`` as the name of the service - project. If you installed RDO using a Puppet-based method, substitute - ``services`` as the project name. - - .. _`Keystone install guide`: https://docs.openstack.org/keystone/latest/install/keystone-users-rdo.html + If installing OpenStack manually following the :keystone-doc:`Keystone + install guide `, the name of the + services project is ``service`` as given above. However, traditional + methods of installing RDO (such as PackStack and TripleO) use + ``services`` as the name of the service project. If you installed RDO + using a Puppet-based method, substitute ``services`` as the project + name. .. note:: diff --git a/doc/source/operating_guides/scale_deployment.rst b/doc/source/operating_guides/scale_deployment.rst index c19d3657fc..0e79fab83e 100644 --- a/doc/source/operating_guides/scale_deployment.rst +++ b/doc/source/operating_guides/scale_deployment.rst @@ -31,12 +31,12 @@ Assumptions This guide, using a devstack installation of OpenStack, assumes that: - 1. You have configured devstack from `Single Machine Installation Guide - `_; - 2. You have set up heat on devstack, as defined at :doc:`heat and DevStack - <../getting_started/on_devstack>`; - 3. You have installed HAProxy_ on the devstack - server. +1. You have configured devstack from :devstack-doc:`Single Machine + Installation Guide `; +2. You have set up heat on devstack, as defined at :doc:`heat and DevStack + <../getting_started/on_devstack>`; +3. You have installed HAProxy_ on the devstack + server. Architecture ============ diff --git a/doc/source/template_guide/multi-clouds.rst b/doc/source/template_guide/multi-clouds.rst index 6509d1a084..e6266db46b 100644 --- a/doc/source/template_guide/multi-clouds.rst +++ b/doc/source/template_guide/multi-clouds.rst @@ -13,10 +13,10 @@ multi-clouds features, and what's the environment requirement. .. note:: If you like to create a stack in multi-region environment, you don't need this feature at all. all you need to do is provide - `region_name` under `context` property for `OS::Heat::Stack`_. + `region_name` under `context` property for :ref:`OS::Heat::Stack`. If you like to see information on how to provide SSL support for your multi-region environment, you can jump to `Use CA - cert(Optional)`_ . + cert (Optional)`_ . Requirements ~~~~~~~~~~~~ @@ -58,17 +58,23 @@ Gathering credential information Before we start generating secret, let's talk about what credential format we need. credential is a JSON format string contains two keys ``auth_type``, and ``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from -Keystone. You can find `plugin options`_ and `authentication plugins`_ in -keystoneauth documents. +Keystone. You can find :keystoneauth-doc:`plugin options +` and :keystoneauth-doc:`authentication plugins +` in keystoneauth +documents. * **auth_type** - ``auth_type`` is a string for plugin name. Allows value like `v3applicationcredential`, `password`, `v3oidcclientcredentials`, etc. You - need to provide `available plugins`_. + need to provide `available plugins + `. * **auth** - auth is a dictionary contains all parameters for plugins to perform authentication. You can find all valid parameter references from - `available plugins`_ or get to all class path from `plugin names`_ for more - detail allowed value or trace plugin class from there. + :keystoneauth-doc:`available plugins + ` or get to all class path from + :keystoneauth-doc:`plugin names + ` for more detail + allowed value or trace plugin class from there. As you can tell, all allowed authentication plugins for credentials follows plugins keystoneauth rules. So once new change in keystoneauth, it will also @@ -81,15 +87,18 @@ Validate your credential ------------------------ Now you have all your credential information ready, try to validate first if -you can. You can either directly test them `via config`_, `via CLI`_, or -`via keystoneauth sessions`_. +you can. You can either directly test them :keystoneauth-doc:`via config +`, +:keystoneauth-doc:`via CLI `, +or :keystoneauth-doc:`via keystoneauth sessions `. build credential secret ----------------------- -Once you're sure it's valid, we can start building the secret out. -To build a secret you just have to follow standard Barbican CLI_ or API to -store your secret. +Once you're sure it's valid, we can start building the secret out. To build a +secret you just have to follow the standard +:python-barbicanclient-doc:`Barbican CLI ` or +API to store your secret. The local site will read this secret to perform stack actions in remote site. Let's give a quick example here: @@ -111,9 +120,8 @@ Create remote stacks Now, you have a secret id generated for your Barbican secret. Use that id as input for template. -To create a remote stack, you can simply use `OS::Heat::Stack`_ resource, as -child stack in your template (we also referring this structure as -`nested stack`). +To create a remote stack, you can simply use an :ref:`OS::Heat::Stack` resource +in your template. In resource properties, provide `credential_secret_id` (Barbican secret ID from the secret we just builded for credential) under `context` property. @@ -146,8 +154,8 @@ won't affect resources/stacks in remote site. So do such actions with super care. -Use CA cert(Optional) ---------------------- +Use CA cert (Optional) +---------------------- For production clouds, it's very important to have SSL support. Here we provide CA cert method for your SSL access. If you wish to use that, use @@ -174,13 +182,3 @@ Here is an example for you: template: { get_file: "remote-app.yaml" } .. note:: If insecure flag is on, ca_cert will be ignored. - -.. _`plugin options`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html -.. _`authentication plugins`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name -.. _`plugin names`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name -.. _`available plugins`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#available-plugins -.. _`via keystoneauth sessions`: https://docs.openstack.org/keystoneauth/latest/using-sessions.html -.. _`via config`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-config-file -.. _`via CLI`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-cli -.. _CLI: https://docs.openstack.org/python-barbicanclient/latest/cli/cli_usage.html#secret-create -.. _`OS::Heat::Stack`: https://docs.openstack.org/heat/rocky/template_guide/openstack.html#OS::Heat::Stack diff --git a/doc/source/template_guide/software_deployment.rst b/doc/source/template_guide/software_deployment.rst index 7f989f8d0d..8f3accebb4 100644 --- a/doc/source/template_guide/software_deployment.rst +++ b/doc/source/template_guide/software_deployment.rst @@ -39,18 +39,21 @@ you might want to do this, including: A number of tools are available for building custom images, including: -* diskimage-builder_ image building tools for OpenStack +* :diskimage-builder-doc:`diskimage-builder <>` image building tools for OpenStack * imagefactory_ builds images for a variety of operating system/cloud combinations -Examples in this guide which require custom images will use diskimage-builder_. +Examples in this guide that require custom images will use +:diskimage-builder-doc:`diskimage-builder <>`. User-data boot scripts and cloud-init ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + When booting a server it is possible to specify the contents of the user-data to be passed to that server. This user-data is made available either from -configured config-drive or from the `Metadata service`_. +configured config-drive or from the :nova-doc:`Metadata service +` How this user-data is consumed depends on the image being booted, but the most commonly used tool for default cloud images is cloud-init_. @@ -779,11 +782,8 @@ contents of the file ``example-puppet-manifest.pp``, containing: } - .. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html -.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/ .. _imagefactory: https://imgfac.org/ -.. _`Metadata service`: https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service .. _cloud-init: https://cloudinit.readthedocs.io/ .. _curl: https://curl.haxx.se/ .. _`Orchestration API`: https://docs.openstack.org/api-ref/orchestration/v1/