Linking to external resources#

We are using the Sphinx external link library extension to create a library of common URL references that can be used to create link references to external resources.

Using the link library provides these advantages:

  • If the URLs to common resources change, you can update the external link library URL specification in the configuration file instead of having to update every link to that resource in the documentation library.
  • Link references are shorter so you don’t have to make as many format adjustments in tables and indented list to accommodate wrapping link text.

The link library URL specification is defined in the Sphinx configuration file for each project.

Example: Common external link library definition from the Sphinx configuration file

 # External link library

 extlinks = {
    'rax': ('https://www.rackspace.com/%s', ''),
    'rax-cart': ('http://cart.rackspace.com/%s', ''),
    'rax-special': ('https://%s.rackspace.com/', ''),
    'rax-cloud': ('https://www.rackspace.com/cloud/%s', ''),
    'rax-dev': ('https://developer.rackspace.com/%s', ''),
    'rax-devdocs': ('https://developer.rackspace.com/docs/%s', ''),
    'rax-api':
      ('https:/developer.rackspace.com/docs/%s/api-reference', ''),
    'rax-git': ('https://github.com/rackspace/%s', ''),
    'mycloud': ('https://mycloud.rackspace.com/%s', ''),
    'rax-glossary': ('https://developer.rackspace.com/docs/glossary/%s', ''),
    'how-to': ('https://support.rackspace.com/how-to/%s', ''),
    'os': ('https://www.openstack.org/%s', ''),
    'os-docs': ('https://docs.openstack.org/%s', ''),
    'os-wiki': ('https://wiki.openstack.org/%s', ''),
    'git-repo': ('https://github.com/rackerlabs/'
                 'docs-core-infra-user-guide/%s', ''),
    'rackerlabs': ('https://github.com/rackerlabs/%s', ''),
    'rocket': ('https://objectrocket.com/%s', '')
}

Linking examples#

When you reference a link using the external link library, the reference identifier (kc-faq, rax-dev, rax-devguide) precedes the link label and the part of the link reference that is variable as represented by the %s in the external link definition.

Link to DRC

:rax-dev:'Rackspace Developer website <>`

Note that the link element is enclosed in <>. If the element is empty, the reference is replaced by the base url. In this example, the link reference is replaced by developer.rackspace.com.

Link to the Docs page

:rax-devdocs:`API Developer Guide <>`

Link to a specific Dev Guide

:rax-devguide:`Cloud Images Developer Guide <cloud-images/v2>`

In this example, the cloud-images/v2 portion replaces the %s in the external link definition defined in the conf.py http://developer.rackspace.com/docs/%s.

Link to API reference for a product

:rax-api:`Cloud Images API Reference <cloud-images/v2>`

Link to a API doc topic

:rax-devdocs:`List images operation <cloud-images/v2/developer-guide/#list-images>`

Link to KC article

:how-to:`Getting Started with Role-Based Access Control (RBAC) <getting-started-with-role-based-access-control-rbac>`

You can see some examples of external link library references to the Rackspace Support How To collection articles in the Core Infrastructure User Guide source files.

Link to Glossary term

:rax-glossary:`term <#term>`

You can get the glossary term links from the anchor links assigned to each term in the published Glossary, for example the agent link is here: https://developer.rackspace.com/docs/glossary/#agent