def __output_doc(self, documented):
if not isinstance(documented, javalang.tree.Documented):
raise ValueError('node not documented')
output = util.Document()
if not documented.documentation:
return output
doc = javalang.javadoc.parse(documented.documentation)
if doc.description:
output.add(self.__html_to_rst(doc.description))
output.clear()
if doc.authors:
output.add_line(':author: %s' % (self.__html_to_rst(', '.join(doc.authors)),))
for name, value in doc.params:
output.add_line(':param %s: %s' % (name, self.__html_to_rst(value)))
for exception in doc.throws:
description = doc.throws[exception]
output.add_line(':throws %s: %s' % (exception, self.__html_to_rst(description)))
if doc.return_doc:
output.add_line(':return: %s' % (self.__html_to_rst(doc.return_doc),))
if doc.tags.get('see'):
output.clear()
see_also = ', '.join(self.__output_see(see) for see in doc.tags['see'])
output.add_line('**See also:** %s' % (see_also,))
return output
def __output_doc(self, documented):
if not isinstance(documented, javalang.tree.Documented):
raise ValueError('node not documented')
output = util.Document()
if not documented.documentation:
return output
doc = javalang.javadoc.parse(documented.documentation)
if doc.description:
output.add(self.__html_to_rst(doc.description))
output.clear()
if doc.authors:
output.add_line(':author: %s' % (self.__html_to_rst(', '.join(doc.authors)),))
for name, value in doc.params:
output.add_line(':param %s: %s' % (name, self.__html_to_rst(value)))
if 'deprecated' in doc.tags:
# the sphinx deprecated tag and the JavaDoc deprecate tag differ
# in that the sphinx tag has a mandatory version argument, whereas
# the JavaDoc deprecated tag only has a version argument.
# Try to find version-like string at the beginning and use that
# if it exists. Otherwise, fall back to hand written deprecation
# statement. It's better than discarding the deprecated tag
# altogether
deprecated = self.__html_to_rst(''.join(doc.tags['deprecated']))
version, rest = self.__find_version(deprecated)
output.clear()
if version:
output.add_line('.. deprecated:: %s\n %s' % (version, rest))
else:
output.add_line('Deprecated: %s' %rest)
if 'since' in doc.tags:
since = self.__html_to_rst(''.join(doc.tags['since']))
output.clear()
output.add_line('.. versionadded:: %s\n' % since)
for exception in doc.throws:
description = doc.throws[exception]
output.add_line(':throws %s: %s' % (exception, self.__html_to_rst(description)))
if doc.return_doc:
output.add_line(':return: %s' % (self.__html_to_rst(doc.return_doc),))
if doc.tags.get('see'):
output.clear()
see_also = ', '.join(self.__output_see(see) for see in doc.tags['see'])
output.add_line('**See also:** %s' % (see_also,))
return output
def tags_document(self):
pos_tokens = []
for sentence in self.pos_tagged_tokens:
sentence_tags = []
for tagged_word in sentence:
word = tagged_word[0]
tag = tagged_word[1]
if tag == "IN" and word in Prepositions.SUPPORTED_PREPOSITIONS:
sentence_tags.append(word)
else:
sentence_tags.append(tag)
pos_tokens.append(sentence_tags)
return util.Document("%s.tag" % self.name, tokens=pos_tokens)
def write_toc(packages, opts):
doc = util.Document()
doc.add_heading(opts.toc_title, '=')
toc = util.Directive('toctree')
toc.add_option('maxdepth', '2')
doc.add_object(toc)
packages = list(packages)
packages.sort()
for package in packages:
toc.add_content(package.replace('.', '/') + '/package-index\n')
filename = 'packages.' + opts.suffix
fullpath = os.path.join(opts.destdir, filename)
if os.path.exists(fullpath) and not (opts.force or opts.update):
sys.stderr.write(fullpath + ' already exists. Use -f to overwrite.\n')
sys.exit(1)
f = open(fullpath, 'w')
f.write(doc.build().encode('utf8'))
f.close()
def compile_type_document(self, imports_block, package, name, declaration):
""" Compile a complete document, documenting a type and its members """
outer_type = name.rpartition('.')[0]
document = util.Document()
document.add(imports_block)
document.add_heading(name, '=')
method_summary = util.StringBuilder()
document.add_object(method_summary)
package_dir = util.Directive('java:package', package)
package_dir.add_option('noindex')
document.add_object(package_dir)
# Add type-level documentation
type_dir = self.compile_type(declaration)
if outer_type:
type_dir.add_option('outertype', outer_type)
document.add_object(type_dir)
if isinstance(declaration, javalang.tree.EnumDeclaration):
enum_constants = list(declaration.body.constants)
enum_constants.sort(key=lambda c: c.name)
document.add_heading('Enum Constants')
for enum_constant in enum_constants:
if self.member_headers:
document.add_heading(enum_constant.name, '^')
c = self.compile_enum_constant(name, enum_constant)
c.add_option('outertype', name)
document.add_object(c)
fields = filter(self.filter, declaration.fields)
if fields:
document.add_heading('Fields', '-')
fields.sort(key=lambda f: f.declarators[0].name)
for field in fields:
if self.member_headers:
document.add_heading(field.declarators[0].name, '^')
f = self.compile_field(field)
f.add_option('outertype', name)
document.add_object(f)
constructors = filter(self.filter, declaration.constructors)
if constructors:
document.add_heading('Constructors', '-')
constructors.sort(key=lambda c: c.name)
for constructor in constructors:
if self.member_headers:
document.add_heading(constructor.name, '^')
c = self.compile_constructor(constructor)
c.add_option('outertype', name)
document.add_object(c)
methods = filter(self.filter, declaration.methods)
if methods:
document.add_heading('Methods', '-')
methods.sort(key=lambda m: m.name)
for method in methods:
if self.member_headers:
document.add_heading(method.name, '^')
m = self.compile_method(method)
m.add_option('outertype', name)
document.add_object(m)
return document
def write_documents(documents, sources, opts):
package_contents = dict()
# Write individual documents
for fullname, (package, name, document) in documents.items():
package_path = package.replace('.', os.sep)
filebasename = name.replace('.', '-')
filename = filebasename + '.' + opts.suffix
dirpath = os.path.join(opts.destdir, package_path)
fullpath = os.path.join(dirpath, filename)
if not os.path.exists(dirpath):
os.makedirs(dirpath)
elif os.path.exists(fullpath) and not (opts.force or opts.update):
sys.stderr.write(fullpath + ' already exists. Use -f to overwrite.\n')
sys.exit(1)
# Add to package indexes
package_contents.setdefault(package, list()).append(filebasename)
if opts.update and os.path.exists(fullpath):
# If the destination file is newer than the source file than skip
# writing it out
source_mod_time = os.stat(sources[fullname]).st_mtime
dest_mod_time = os.stat(fullpath).st_mtime
if source_mod_time < dest_mod_time:
continue
f = open(fullpath, 'w')
f.write(document.encode('utf8'))
f.close()
# Write package-index for each package
for package, index in package_contents.items():
doc = util.Document()
doc.add_heading(package, '=')
doc.add_object(util.Directive('java:package', package))
toc = util.Directive('toctree')
toc.add_option('maxdepth', '1')
doc.add_object(toc)
index.sort()
for filebasename in index:
toc.add_content(filebasename + '\n')
package_path = package.replace('.', os.sep)
filename = 'package-index.' + opts.suffix
dirpath = os.path.join(opts.destdir, package_path)
fullpath = os.path.join(dirpath, filename)
if not os.path.exists(dirpath):
os.makedirs(dirpath)
elif os.path.exists(fullpath) and not (opts.force or opts.update):
sys.stderr.write(fullpath + ' already exists. Use -f to overwrite.\n')
sys.exit(1)
f = open(fullpath, 'w')
f.write(doc.build().encode('utf8'))
f.close()