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
|
Set up the Sphinx extension. |
|
Register roles for each external link that's been defined. |
Classes
|
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.- __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
- __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
- 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.
- 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: