Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
1586bc21c057f8e8ee6b9032a3f3584b0e0bfe4a
[simgrid.git] / 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], []