docs/source/_ext/javasphinx/extdoc.py

   1 #
   2 # Copyright 2012-2015 Bronto Software, Inc. and contributors
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 #
  16
  17 import re
  18
  19 from docutils import nodes, utils
  20 from sphinx.util.nodes import split_explicit_title
  21
  22 def get_javadoc_ref(app, rawtext, text):
  23     javadoc_url_map = app.config.javadoc_url_map
  24
  25     # Add default Java SE sources
  26     if not javadoc_url_map.get("java"):
  27         javadoc_url_map["java"] = ("http://docs.oracle.com/javase/8/docs/api", 'javadoc8')
  28     if not javadoc_url_map.get("javax"):
  29         javadoc_url_map["javax"] = ("http://docs.oracle.com/javase/8/docs/api", 'javadoc8')
  30     if not javadoc_url_map.get("org.xml"):
  31         javadoc_url_map["org.xml"] = ("http://docs.oracle.com/javase/8/docs/api", 'javadoc8')
  32     if not javadoc_url_map.get("org.w3c"):
  33         javadoc_url_map["org.w3c"] = ("http://docs.oracle.com/javase/8/docs/api", 'javadoc8')
  34
  35     source = None
  36     package = ''
  37     method = None
  38
  39     if '(' in text:
  40         # If the javadoc contains a line like this:
  41         # {@link #sort(List)}
  42         # there is no package so the text.rindex will fail
  43         try:
  44             split_point = text.rindex('.', 0, text.index('('))
  45             method = text[split_point + 1:]
  46             text = text[:split_point]
  47         except ValueError:
  48             pass
  49
  50     for pkg, (baseurl, ext_type) in javadoc_url_map.items():
  51         if text.startswith(pkg + '.') and len(pkg) > len(package):
  52             source = baseurl, ext_type
  53             package = pkg
  54
  55     if not source:
  56         return None
  57
  58     baseurl, ext_type = source
  59
  60     package_parts = []
  61     cls_parts = []
  62
  63     for part in text.split('.'):
  64         if cls_parts or part[0].isupper():
  65             cls_parts.append(part)
  66         else:
  67             package_parts.append(part)
  68
  69     package = '.'.join(package_parts)
  70     cls = '.'.join(cls_parts)
  71
  72     if not baseurl.endswith('/'):
  73         baseurl = baseurl + '/'
  74
  75     if ext_type == 'javadoc':
  76         if not cls:
  77             cls = 'package-summary'
  78         source = baseurl + package.replace('.', '/') + '/' + cls + '.html'
  79         if method:
  80             source = source + '#' + method
  81     elif ext_type == 'javadoc8':
  82         if not cls:
  83             cls = 'package-summary'
  84         source = baseurl + package.replace('.', '/') + '/' + cls + '.html'
  85         if method:
  86             source = source + '#' + re.sub(r'[()]', '-', method)
  87     elif ext_type == 'sphinx':
  88         if not cls:
  89             cls = 'package-index'
  90         source = baseurl + package.replace('.', '/') + '/' + cls.replace('.', '-') + '.html'
  91         if method:
  92             source = source + '#' + package + '.' + cls + '.' + method
  93     else:
  94         raise ValueError('invalid target specifier ' + ext_type)
  95
  96     title = '.'.join(filter(None, (package, cls, method)))
  97     node = nodes.reference(rawtext, '')
  98     node['refuri'] = source
  99     node['reftitle'] = title
 100
 101     return node
 102
 103 def javadoc_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
 104     """ Role for linking to external Javadoc """
 105
 106     has_explicit_title, title, target = split_explicit_title(text)
 107     title = utils.unescape(title)
 108     target = utils.unescape(target)
 109
 110     if not has_explicit_title:
 111         target = target.lstrip('~')
 112
 113         if title[0] == '~':
 114             title = title[1:].rpartition('.')[2]
 115
 116     app = inliner.document.settings.env.app
 117     ref = get_javadoc_ref(app, rawtext, target)
 118
 119     if not ref:
 120          raise ValueError("no Javadoc source found for %s in javadoc_url_map" % (target,))
 121
 122     ref.append(nodes.Text(title, title))
 123
 124     return [ref], []