# beanbag_docutils.sphinx.ext.extlinks

Sphinx extension to define external links that support anchors.

Sphinx comes bundled with a `sphinx.ext.extlinks` extension, which allows a `conf.py` to define roles for external links. These don’t support anchors, however, making it impossible to link to properly link in some cases.

This is a wrapper around that module that looks for anchors and appends them to the resulting URL.

## Setup

This extension works identically to `sphinx.ext.extlinks` and contains the same configuration. To use it, configure external links the way you would for that extension, but add ours instead to `conf.py`:

    extensions = [
        ...
        'beanbag_docutils.sphinx.ext.extlinks',
        ...
    ]

Functions

`setup`(app) | Set up the Sphinx extension.
`setup_link_roles`(app) | Register roles for each external link that's been defined.

Classes

`ExternalLink`(base_url) | Wraps a URL and formats references to allow for using anchors.

class beanbag_docutils.sphinx.ext.extlinks.ExternalLink(base_url)

  Bases: `object`

  Wraps a URL and formats references to allow for using anchors.

  This will work like a string, from the point of view of `sphinx.ext.extlinks`. It takes the URL for the external link and intercepts any string formatting, pulling out the anchor and appending it to the final result.

  __add__(s)

    Return the concatenated string for the base URL and another string.

    Parameters:

      s (`unicode`) – A string to concatenate onto this base URL.

    Returns:

      The concatenated string.

    Return type:

      `unicode`

  __firstlineno__ = 30
  __init__(base_url)

    Initialize the class.

    Parameters:

      base_url (`unicode`) – The URL to wrap. This must contain a `%s`.

  __mod__(ref)

    Return a URL based on the stored string format and the reference.

    Parameters:

      ref (`unicode`) – The reference to place into the URL. This may contain an anchor starting with `#`.

    Returns:

      The formatted URL.

    Return type:

      `unicode`

  __static_attributes__ = ('base_url',)

beanbag_docutils.sphinx.ext.extlinks.setup(app)

  Set up the Sphinx extension.

  This registers the configuration for external links and adds the roles for each when the builder initializes.

  Parameters:

    app (`sphinx.application.Sphinx`) – The Sphinx application.

  Returns:

    Information about the extension. This is in the same format as what `sphinx.ext.extlinks.setup()` returns.

  Return type:

    `dict`

beanbag_docutils.sphinx.ext.extlinks.setup_link_roles(app)

  Register roles for each external link that’s been defined.

  Parameters:

    app (`sphinx.application.Sphinx`) – The Sphinx application.