docs/source/_ext/javasphinx/javasphinx/domain.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 import string
  19
  20 from docutils import nodes
  21 from docutils.parsers.rst import Directive, directives
  22
  23 from sphinx import addnodes, version_info
  24 from sphinx.roles import XRefRole
  25 from sphinx.locale import _
  26 from sphinx.domains import Domain, ObjType
  27 from sphinx.directives import ObjectDescription
  28 from sphinx.util.nodes import make_refnode
  29 from sphinx.util.docfields import Field, TypedField, GroupedField
  30
  31 import javalang
  32
  33 import javasphinx.extdoc as extdoc
  34 import javasphinx.formatter as formatter
  35 import javasphinx.util as util
  36
  37 # Classes in java.lang. These are available without an import.
  38 java_dot_lang = set([
  39     'AbstractMethodError', 'Appendable', 'ArithmeticException',
  40     'ArrayIndexOutOfBoundsException', 'ArrayStoreException', 'AssertionError',
  41     'AutoCloseable', 'Boolean', 'BootstrapMethodError', 'Byte', 'Character',
  42     'CharSequence', 'Class', 'ClassCastException', 'ClassCircularityError',
  43     'ClassFormatError', 'ClassLoader', 'ClassNotFoundException', 'ClassValue',
  44     'Cloneable', 'CloneNotSupportedException', 'Comparable', 'Compiler',
  45     'Deprecated', 'Double', 'Enum', 'EnumConstantNotPresentException', 'Error',
  46     'Exception', 'ExceptionInInitializerError', 'Float', 'IllegalAccessError',
  47     'IllegalAccessException', 'IllegalArgumentException',
  48     'IllegalMonitorStateException', 'IllegalStateException',
  49     'IllegalThreadStateException', 'IncompatibleClassChangeError',
  50     'IndexOutOfBoundsException', 'InheritableThreadLocal', 'InstantiationError',
  51     'InstantiationException', 'Integer', 'InternalError', 'InterruptedException',
  52     'Iterable', 'LinkageError', 'Long', 'Math', 'NegativeArraySizeException',
  53     'NoClassDefFoundError', 'NoSuchFieldError', 'NoSuchFieldException',
  54     'NoSuchMethodError', 'NoSuchMethodException', 'NullPointerException', 'Number',
  55     'NumberFormatException', 'Object', 'OutOfMemoryError', 'Override', 'Package',
  56     'Process', 'ProcessBuilder', 'Readable', 'ReflectiveOperationException',
  57     'Runnable', 'Runtime', 'RuntimeException', 'RuntimePermission', 'SafeVarargs',
  58     'SecurityException', 'SecurityManager', 'Short', 'StackOverflowError',
  59     'StackTraceElement', 'StrictMath', 'String', 'StringBuffer', 'StringBuilder',
  60     'StringIndexOutOfBoundsException', 'SuppressWarnings', 'System', 'Thread',
  61     'ThreadDeath', 'ThreadGroup', 'ThreadLocal', 'Throwable',
  62     'TypeNotPresentException', 'UnknownError', 'UnsatisfiedLinkError',
  63     'UnsupportedClassVersionError', 'UnsupportedOperationException', 'VerifyError',
  64     'VirtualMachineError', 'Void'])
  65
  66 class JavaObject(ObjectDescription):
  67     option_spec = {
  68         'noindex': directives.flag,
  69         'package': directives.unchanged,
  70         'outertype': directives.unchanged
  71     }
  72
  73     def _build_ref_node(self, target):
  74         ref = addnodes.pending_xref('', refdomain='java', reftype='type', reftarget=target, modname=None, classname=None)
  75         ref['java:outertype'] = self.get_type()
  76
  77         package = self.env.temp_data.get('java:imports', dict()).get(target, None)
  78
  79         if not package and target in java_dot_lang:
  80             package = 'java.lang'
  81
  82         if package:
  83             ref['java:imported'] = True
  84             ref['java:package'] = package
  85         else:
  86             ref['java:imported'] = False
  87             ref['java:package'] = self.get_package()
  88
  89         return ref
  90
  91     def _build_type_node(self, typ):
  92         if isinstance(typ, javalang.tree.ReferenceType):
  93             if typ.dimensions:
  94                 dim = '[]' * len(typ.dimensions)
  95             else:
  96                 dim = ''
  97
  98             target = typ.name
  99             parts = []
 100
 101             while typ:
 102                 ref_node = self._build_ref_node(target)
 103                 ref_node += nodes.Text(typ.name, typ.name)
 104                 parts.append(ref_node)
 105
 106                 if typ.arguments:
 107                     parts.append(nodes.Text('<', '<'))
 108
 109                     first = True
 110                     for type_arg in typ.arguments:
 111                         if first:
 112                             first = False
 113                         else:
 114                             parts.append(nodes.Text(', ', ', '))
 115
 116                         if type_arg.pattern_type == '?':
 117                             parts.append(nodes.Text('?', '?'))
 118                         else:
 119                             if type_arg.pattern_type:
 120                                 s = '? %s ' % (type_arg.pattern_type,)
 121                                 parts.append(nodes.Text(s, s))
 122                             parts.extend(self._build_type_node(type_arg.type))
 123
 124                     parts.append(nodes.Text('>', '>'))
 125
 126                 typ = typ.sub_type
 127
 128                 if typ:
 129                     target = target + '.' + typ.name
 130                     parts.append(nodes.Text('.', '.'))
 131                 elif dim:
 132                     parts.append(nodes.Text(dim, dim))
 133
 134             return parts
 135
 136         type_repr = formatter.output_type(typ).build()
 137         return [nodes.Text(type_repr, type_repr)]
 138
 139     def _build_type_node_list(self, types):
 140         parts = self._build_type_node(types[0])
 141         for typ in types[1:]:
 142             parts.append(nodes.Text(', ', ', '))
 143             parts.extend(self._build_type_node(typ))
 144         return parts
 145
 146     def handle_signature(self, sig, signode):
 147         handle_name = 'handle_%s_signature' % (self.objtype,)
 148         handle = getattr(self, handle_name, None)
 149
 150         if handle:
 151             return handle(sig, signode)
 152         raise NotImplementedError
 153
 154     def get_index_text(self, package, typ, name):
 155         raise NotImplementedError
 156
 157     def get_package(self):
 158         return self.options.get('package', self.env.temp_data.get('java:package'))
 159
 160     def get_type(self):
 161         return self.options.get('outertype', '.'.join(self.env.temp_data.get('java:outertype', [])))
 162
 163     def add_target_and_index(self, name, sig, signode):
 164         package = self.get_package()
 165         typ = self.get_type()
 166
 167         fullname = '.'.join(filter(None, (package, typ, name)))
 168         basename = fullname.partition('(')[0]
 169
 170         # note target
 171         if fullname not in self.state.document.ids:
 172             signode['names'].append(fullname)
 173             signode['ids'].append(fullname)
 174             signode['first'] = (not self.names)
 175             self.state.document.note_explicit_target(signode)
 176
 177             objects = self.env.domaindata['java']['objects']
 178             if fullname in objects:
 179                 self.state_machine.reporter.warning(
 180                     'duplicate object description of %s, ' % fullname +
 181                     'other instance in ' + self.env.doc2path(objects[fullname][0]) +
 182                     ', use :noindex: for one of them',
 183                     line=self.lineno)
 184
 185             objects[fullname] = (self.env.docname, self.objtype, basename)
 186
 187         indextext = self.get_index_text(package, typ, name)
 188         if indextext:
 189             self.indexnode['entries'].append(_create_indexnode(indextext, fullname))
 190
 191     def before_content(self):
 192         self.set_type = False
 193
 194         if self.objtype == 'type' and self.names:
 195             self.set_type = True
 196             self.env.temp_data.setdefault('java:outertype', list()).append(self.names[0])
 197
 198     def after_content(self):
 199         if self.set_type:
 200             self.env.temp_data['java:outertype'].pop()
 201
 202 class JavaMethod(JavaObject):
 203     doc_field_types = [
 204         TypedField('parameter', label=_('Parameters'),
 205                    names=('param', 'parameter', 'arg', 'argument'),
 206                    typerolename='type', typenames=('type',)),
 207         Field('returnvalue', label=_('Returns'), has_arg=False,
 208               names=('returns', 'return')),
 209         GroupedField('throws', names=('throws',), label=_('Throws'), rolename='type')
 210     ]
 211
 212     def handle_method_signature(self, sig, signode):
 213         try:
 214             member = javalang.parse.parse_member_signature(sig)
 215         except javalang.parser.JavaSyntaxError:
 216             raise self.error("syntax error in method signature")
 217
 218         if not isinstance(member, javalang.tree.MethodDeclaration):
 219             raise self.error("expected method declaration")
 220
 221         mods = formatter.output_modifiers(member.modifiers).build()
 222         signode += nodes.Text(mods + ' ', mods + ' ')
 223
 224         if member.type_parameters:
 225             type_params = formatter.output_type_params(member.type_parameters).build()
 226             signode += nodes.Text(type_params, type_params)
 227             signode += nodes.Text(' ', ' ')
 228
 229         rnode = addnodes.desc_type('', '')
 230         rnode += self._build_type_node(member.return_type)
 231
 232         signode += rnode
 233         signode += nodes.Text(' ', ' ')
 234         signode += addnodes.desc_name(member.name, member.name)
 235
 236         paramlist = addnodes.desc_parameterlist()
 237         for parameter in member.parameters:
 238             param = addnodes.desc_parameter('', '', noemph=True)
 239             param += self._build_type_node(parameter.type)
 240
 241             if parameter.varargs:
 242                 param += nodes.Text('...', '')
 243
 244             param += nodes.emphasis(' ' + parameter.name, ' ' + parameter.name)
 245             paramlist += param
 246         signode += paramlist
 247
 248         param_reprs = [formatter.output_type(param.type, with_generics=False).build() for param in member.parameters]
 249         return member.name + '(' + ', '.join(param_reprs) + ')'
 250
 251     def get_index_text(self, package, typ, name):
 252         return _('%s (Java method)' % (name,))
 253
 254 class JavaConstructor(JavaObject):
 255     doc_field_types = [
 256         TypedField('parameter', label=_('Parameters'),
 257                    names=('param', 'parameter', 'arg', 'argument'),
 258                    typerolename='type', typenames=('type',)),
 259         GroupedField('throws', names=('throws',), label=_('Throws'))
 260     ]
 261
 262     def handle_constructor_signature(self, sig, signode):
 263         try:
 264             member = javalang.parse.parse_constructor_signature(sig)
 265         except javalang.parser.JavaSyntaxError:
 266             raise self.error("syntax error in constructor signature")
 267
 268         if not isinstance(member, javalang.tree.ConstructorDeclaration):
 269             raise self.error("expected constructor declaration")
 270
 271         mods = formatter.output_modifiers(member.modifiers).build()
 272         signode += nodes.Text(mods + ' ', mods + ' ')
 273
 274         signode += addnodes.desc_name(member.name, member.name)
 275
 276         paramlist = addnodes.desc_parameterlist()
 277         for parameter in member.parameters:
 278             param = addnodes.desc_parameter('', '', noemph=True)
 279             param += self._build_type_node(parameter.type)
 280
 281             if parameter.varargs:
 282                 param += nodes.Text('...', '')
 283
 284             param += nodes.emphasis(' ' + parameter.name, ' ' + parameter.name)
 285             paramlist += param
 286         signode += paramlist
 287
 288         param_reprs = [formatter.output_type(param.type, with_generics=False).build() for param in member.parameters]
 289         return '%s(%s)' % (member.name, ', '.join(param_reprs))
 290
 291     def get_index_text(self, package, typ, name):
 292         return _('%s (Java constructor)' % (name,))
 293
 294 class JavaType(JavaObject):
 295     doc_field_types = [
 296         GroupedField('parameter', names=('param',), label=_('Parameters'))
 297     ]
 298
 299     declaration_type = None
 300
 301     def handle_type_signature(self, sig, signode):
 302         try:
 303             member = javalang.parse.parse_type_signature(sig)
 304         except javalang.parser.JavaSyntaxError:
 305             raise self.error("syntax error in field signature")
 306
 307         if isinstance(member, javalang.tree.ClassDeclaration):
 308             self.declaration_type = 'class'
 309         elif isinstance(member, javalang.tree.InterfaceDeclaration):
 310             self.declaration_type = 'interface'
 311         elif isinstance(member, javalang.tree.EnumDeclaration):
 312             self.declaration_type = 'enum'
 313         elif isinstance(member, javalang.tree.AnnotationDeclaration):
 314             self.declaration_type = 'annotation'
 315         else:
 316             raise self.error("expected type declaration")
 317
 318         mods = formatter.output_modifiers(member.modifiers).build()
 319         signode += nodes.Text(mods + ' ', mods + ' ')
 320
 321         if self.declaration_type == 'class':
 322             signode += nodes.Text('class ', 'class ')
 323         elif self.declaration_type == 'interface':
 324             signode += nodes.Text('interface ', 'interface ')
 325         elif self.declaration_type == 'enum':
 326             signode += nodes.Text('enum ', 'enum ')
 327         elif self.declaration_type == 'annotation':
 328             signode += nodes.Text('@interface ', '@interface ')
 329
 330         signode += addnodes.desc_name(member.name, member.name)
 331
 332         if self.declaration_type in ('class', 'interface') and member.type_parameters:
 333             type_params = formatter.output_type_params(member.type_parameters).build()
 334             signode += nodes.Text(type_params, type_params)
 335
 336         if self.declaration_type == 'class':
 337             if member.extends:
 338                 extends = ' extends '
 339                 signode += nodes.Text(extends, extends)
 340                 signode += self._build_type_node(member.extends)
 341             if member.implements:
 342                 implements = ' implements '
 343                 signode += nodes.Text(implements, implements)
 344                 signode += self._build_type_node_list(member.implements)
 345         elif self.declaration_type == 'interface':
 346             if member.extends:
 347                 extends = ' extends '
 348                 signode += nodes.Text(extends, extends)
 349                 signode += self._build_type_node_list(member.extends)
 350         elif self.declaration_type == 'enum':
 351             if member.implements:
 352                 implements = ' implements '
 353                 signode += nodes.Text(implements, implements)
 354                 signode += self._build_type_node_list(member.implements)
 355
 356         return member.name
 357
 358     def get_index_text(self, package, typ, name):
 359         return _('%s (Java %s)' % (name, self.declaration_typ))
 360
 361 class JavaField(JavaObject):
 362     def handle_field_signature(self, sig, signode):
 363         try:
 364             member = javalang.parse.parse_member_signature(sig)
 365         except javalang.parser.JavaSyntaxError:
 366             raise self.error("syntax error in field signature")
 367
 368         if not isinstance(member, javalang.tree.FieldDeclaration):
 369             raise self.error("expected field declaration")
 370
 371         mods = formatter.output_modifiers(member.modifiers).build()
 372         signode += nodes.Text(mods + ' ', mods + ' ')
 373
 374         tnode = addnodes.desc_type('', '')
 375         tnode += self._build_type_node(member.type)
 376
 377         signode += tnode
 378         signode += nodes.Text(' ', ' ')
 379
 380         if len(member.declarators) > 1:
 381             self.error('only one field may be documented at a time')
 382
 383         declarator = member.declarators[0]
 384         signode += addnodes.desc_name(declarator.name, declarator.name)
 385
 386         dim = '[]' * len(declarator.dimensions)
 387         signode += nodes.Text(dim)
 388
 389         if declarator.initializer and isinstance(declarator.initializer, javalang.tree.Literal):
 390             signode += nodes.Text(' = ' + declarator.initializer.value)
 391
 392         return declarator.name
 393
 394     def get_index_text(self, package, typ, name):
 395         return _('%s (Java field)' % (name,))
 396
 397 class JavaPackage(Directive):
 398     """
 399     Directive to mark description of a new package.
 400     """
 401
 402     has_content = False
 403     required_arguments = 1
 404     optional_arguments = 0
 405     final_argument_whitespace = False
 406     option_spec = {
 407         'noindex': directives.flag,
 408     }
 409
 410     def run(self):
 411         env = self.state.document.settings.env
 412         package = self.arguments[0].strip()
 413         noindex = 'noindex' in self.options
 414         env.temp_data['java:package'] = package
 415         env.domaindata['java']['objects'][package] = (env.docname, 'package', package)
 416         ret = []
 417
 418         if not noindex:
 419             targetnode = nodes.target('', '', ids=['package-' + package], ismod=True)
 420             self.state.document.note_explicit_target(targetnode)
 421
 422             # the platform and synopsis aren't printed; in fact, they are only
 423             # used in the modindex currently
 424             ret.append(targetnode)
 425
 426             indextext = _('%s (package)') % (package,)
 427             inode = addnodes.index(entries=[_create_indexnode(indextext, 'package-' + package)])
 428             ret.append(inode)
 429
 430         return ret
 431
 432 class JavaImport(Directive):
 433     """
 434     This directive is just to tell Sphinx the source of a referenced type.
 435     """
 436
 437     has_content = False
 438     required_arguments = 2
 439     optional_arguments = 0
 440     final_argument_whitespace = False
 441     option_spec = {}
 442
 443     def run(self):
 444         env = self.state.document.settings.env
 445         package, typename = self.arguments
 446
 447         env.temp_data.setdefault('java:imports', dict())[typename] = package
 448         return []
 449
 450 class JavaXRefRole(XRefRole):
 451     def process_link(self, env, refnode, has_explicit_title, title, target):
 452         refnode['java:outertype'] = '.'.join(env.temp_data.get('java:outertype', list()))
 453
 454         target = target.lstrip('~')
 455
 456         # Strip a method component from the target
 457         basetype = target
 458         if '(' in basetype:
 459             basetype = basetype.partition('(')[0]
 460             if '.' in basetype:
 461                 basetype = basetype.rpartition('.')[0]
 462
 463         package = env.temp_data.get('java:imports', dict()).get(basetype, None)
 464
 465         if package:
 466             refnode['java:imported'] = True
 467             refnode['java:package'] = package
 468         else:
 469             refnode['java:imported'] = False
 470             refnode['java:package'] = env.temp_data.get('java:package')
 471
 472         if not has_explicit_title:
 473             # if the first character is a tilde, don't display the module/class
 474             # parts of the contents
 475             if title[0:1] == '~':
 476                 title = title.partition('(')[0]
 477                 title = title[1:]
 478                 dot = title.rfind('.')
 479                 if dot != -1:
 480                     title = title[dot+1:]
 481
 482         return title, target
 483
 484 class JavaDomain(Domain):
 485     """Java language domain."""
 486     name = 'java'
 487     label = 'Java'
 488
 489     object_types = {
 490         'package':     ObjType(_('package'), 'package', 'ref'),
 491         'type':        ObjType(_('type'), 'type', 'ref'),
 492         'field':       ObjType(_('field'), 'field', 'ref'),
 493         'constructor': ObjType(_('constructor'), 'construct', 'ref'),
 494         'method':      ObjType(_('method'), 'meth', 'ref')
 495     }
 496
 497     directives = {
 498         'package':        JavaPackage,
 499         'type':           JavaType,
 500         'field':          JavaField,
 501         'constructor':    JavaConstructor,
 502         'method':         JavaMethod,
 503         'import':         JavaImport
 504     }
 505
 506     roles = {
 507         'package':   JavaXRefRole(),
 508         'type':      JavaXRefRole(),
 509         'field':     JavaXRefRole(),
 510         'construct': JavaXRefRole(),
 511         'meth':      JavaXRefRole(),
 512         'ref':       JavaXRefRole(),
 513     }
 514
 515     initial_data = {
 516         'objects': {},  # fullname -> docname, objtype, basename
 517     }
 518
 519     def clear_doc(self, docname):
 520         objects = dict(self.data['objects'])
 521
 522         for fullname, (fn, _, _) in objects.items():
 523             if fn == docname:
 524                 del self.data['objects'][fullname]
 525
 526     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
 527         objects = self.data['objects']
 528         package = node.get('java:package')
 529         imported = node.get('java:imported')
 530         type_context = node.get('java:outertype')
 531
 532         # Partial function to make building the response easier
 533         make_ref = lambda fullname: make_refnode(builder, fromdocname, objects[fullname][0], fullname, contnode, fullname)
 534
 535         # Check for fully qualified references
 536         if target in objects:
 537             return make_ref(target)
 538
 539         # Try with package name prefixed
 540         if package:
 541             fullname = package + '.' + target
 542             if fullname in objects:
 543                 return make_ref(fullname)
 544
 545         # Try with package and type prefixed
 546         if package and type_context:
 547             fullname = package + '.' + type_context + '.' + target
 548             if fullname in objects:
 549                 return make_ref(fullname)
 550
 551         # Try to find a matching suffix
 552         suffix = '.' + target
 553         basename_match = None
 554         basename_suffix = suffix.partition('(')[0]
 555
 556         for fullname, (_, _, basename) in objects.items():
 557             if fullname.endswith(suffix):
 558                 return make_ref(fullname)
 559             if basename.endswith(basename_suffix):
 560                 basename_match = fullname
 561
 562         if basename_match:
 563             return make_ref(basename_match)
 564
 565         # Try creating an external documentation reference
 566         ref = extdoc.get_javadoc_ref(self.env, target, target)
 567
 568         if not ref and target in java_dot_lang:
 569             fulltarget = 'java.lang.' + target
 570             ref = extdoc.get_javadoc_ref(self.env, fulltarget, fulltarget)
 571
 572         # If the target was imported try with the package prefixed
 573         if not ref and imported:
 574             fulltarget = package + '.' + target
 575             ref = extdoc.get_javadoc_ref(self.env, fulltarget, fulltarget)
 576
 577         if ref:
 578             ref.append(contnode)
 579             return ref
 580         return None
 581
 582     def get_objects(self):
 583         for refname, (docname, typ, _) in self.data['objects'].items():
 584             yield (refname, refname, typ, docname, refname, 1)
 585
 586
 587 def _create_indexnode(indextext, fullname):
 588     # See https://github.com/sphinx-doc/sphinx/issues/2673
 589     if version_info < (1, 4):
 590         return ('single', indextext, fullname, '')
 591     return ('single', indextext, fullname, '', None)