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, ))
# Adding cms tags for 3di CMS
# if doc.tags.get('cms.product'):
# product = doc.tags['cms.product']
product = 'MPI'
# Debug - simplest possible output
print('Adding simple fixed meta strings')
output.add_line('.. meta::')
output.add_line(' :product: %s' % product)
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)))
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 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())
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 = list(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 = list(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 = list(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)
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())
f.close()