doc/_extensions/mitgcm.py

f15a57b34c Oliv*0001 """
                0002 Sphinx extension for the MITgcm documentation
                0003
                0004 Provides two custom roles:
                0005
                0006 :filelink:`path/to/file`
                0007   inserts a link to the file on github.  The full path will be shown unless an
                0008   explicit title is given as in :filelink:`title <path/to/file>` or the path is
                0009   prefixed with a tilde, :filelink:`~path/to/file`, in which case only the last
                0010   path component (file) is shown.
                0011
                0012 :varlink:`identifier`
                0013   inserts a link to a code search based on lxr.
                0014
                0015 Slightly modified from http://protips.readthedocs.io/link-roles.html.
                0016 """
                0017
                0018 from docutils import nodes, utils
                0019
                0020 from sphinx.util.nodes import split_explicit_title
                0021
                0022
                0023 def setup(app):
                0024     app.add_role(
                0025         'filelink',
                0026         filelink('https://github.com/MITgcm/MITgcm/blob/master/%s'))
                0027     app.add_role(
                0028         'varlink',
dbc14de275 Jeff*0029         autolink('http://lxr.mitgcm.org/lxr2/ident/MITgcm?_i=%s'))
f15a57b34c Oliv*0030
                0031 def filelink(pattern):
                0032     """
                0033     Return a role processor for external links to files based on a URL pattern.
                0034
                0035     %s in *pattern* will be replaced by the role text, a file path, with two
                0036     modifications:
                0037
                0038     - an explicit title can be specified as for internal sphinx cross
                0039       references: :role:`title <target>` will display *title* but link to a URL
                0040       formed from *target*.
                0041     - if the role text is prefixed with ~, only the last path component will be
                0042       displayed: :role:`~path/to/file` will display *file* but link to
                0043       path/to/file.
                0044     """
                0045     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
                0046         # extract explicit title if provided
                0047         text = utils.unescape(text)
                0048         has_explicit_title, title, part = split_explicit_title(text)
                0049         # if not, check for initial tilde
                0050         if not has_explicit_title and part[:1] == '~':
                0051             # remove it
                0052             part = part[1:]
                0053             # and extract last path component
                0054             title = part.split('/')[-1]
                0055         # form link target
                0056         url = pattern % (part,)
                0057         # make link node
                0058         node = nodes.reference(rawtext, title, refuri=url, **options)
                0059         # and return it (no messages)
                0060         return [node], []
                0061     return role
                0062
                0063 def autolink(pattern):
                0064     """
                0065     Return a role processor for external links based on a URL pattern.
                0066
                0067     %s in *pattern* will be replaced by the role text.
                0068     """
                0069     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
                0070         url = pattern % (text,)
                0071         node = nodes.reference(rawtext, text, refuri=url, **options)
                0072         return [node], []
                0073     return role