def get_class_rst(cls):
"""
Gets rst text to describe a class
Only lists members in summary tables with hyperlinks to other rst docs, with the exception of __init__
which is described in class rst text, below the summary tables.
"""
sorted_members = get_member_rst_list(cls) # sort defs for both summary table and attribute tables
toctree = indent("\n".join([m.rst_name for m in sorted_members]))
starter = """
.. toctree::
:hidden:
{toctree}
.. class:: {name}
{rst_doc}""".format(toctree=toctree, name=get_type_name(cls), rst_doc=indent(cls.__doc__))
lines = [starter]
lines.append(indent(get_attribute_summary_table(sorted_members), 4))
lines.append(indent(get_method_summary_table(sorted_members), 4))
installation = get_installation(cls)
init_commands = [c for c in installation.commands if c.is_constructor]
if init_commands:
lines.append("\n.. _%s:\n" % get_cls_init_rst_label(cls)) # add rst label for internal reference
lines.append(get_command_def_rst(init_commands[0]))
return "\n".join(lines)
def _get_returns_rest_rst(return_info):
return """
``{data_type}``
{description}
""".format(data_type=get_type_name(return_info.data_type), description=indent(return_info.doc, 8)) if return_info\
else "<Missing Return Information>"
def write_py_rst_attr_file(root_path, cls, attr):
command_def = attr.command
header = get_rst_attr_file_header(class_name=get_type_name(cls), index_ref=get_index_ref(cls), attr_name=attr.__name__) #command_def.name)
content = get_command_def_rst(command_def)
folder = get_rst_folder_path(root_path, cls, attr)
file_path = os.path.join(folder, command_def.name + ".rst")
write_text_to_file(file_path, [header, content])
def write_py_rst_attr_file(root_path, cls, attr):
command_def = attr.command
header = get_rst_attr_file_header(class_name=get_type_name(cls), index_ref=get_index_ref(cls), attr_name=attr.__name__) #command_def.name)
content = get_command_def_rst(command_def)
folder = get_rst_folder_path(root_path, cls, attr)
file_path = os.path.join(folder, command_def.name + ".rst")
write_text_to_file(file_path, [header, content])
def get_class_rst(cls):
"""
Gets rst text to describe a class
Only lists members in summary tables with hyperlinks to other rst docs, with the exception of __init__
which is described in class rst text, below the summary tables.
"""
sorted_members = get_member_rst_list(cls) # sort defs for both summary table and attribute tables
toctree = indent("\n".join([m.rst_name for m in sorted_members]))
starter = """
.. toctree::
:hidden:
{toctree}
.. class:: {name}
{rst_doc}""".format(toctree=toctree, name=get_type_name(cls), rst_doc=indent(cls.__doc__))
lines = [starter]
lines.append(indent(get_attribute_summary_table(sorted_members), 4))
lines.append(indent(get_method_summary_table(sorted_members), 4))
installation = get_installation(cls)
init_commands = [c for c in installation.commands if c.is_constructor]
if init_commands:
lines.append("\n.. _%s:\n" % get_cls_init_rst_label(cls)) # add rst label for internal reference
lines.append(get_command_def_rst(init_commands[0]))
return "\n".join(lines)
def write_py_rst_cls_file(root_path, cls):
installation = get_installation(cls)
entity_collection_name = installation.install_path.entity_collection_name
header = get_rst_cls_file_header(entity_collection_name, class_name=get_type_name(cls))
content = get_class_rst(cls)
folder = get_rst_folder_path(root_path, cls)
file_path = os.path.join(folder, "index.rst")
write_text_to_file(file_path, [header, content])
def write_py_rst_cls_file(root_path, cls):
installation = get_installation(cls)
entity_collection_name = installation.install_path.entity_collection_name
header = get_rst_cls_file_header(entity_collection_name, class_name=get_type_name(cls))
content = get_class_rst(cls)
folder = get_rst_folder_path(root_path, cls)
file_path = os.path.join(folder, "index.rst")
write_text_to_file(file_path, [header, content])
def get_class_command_names(self):
return sorted(
set([
"%s.%s" % (get_type_name(cls),
str(c.name) if c.name != 'new' else '__init__')
for cls, commands in self.command_defs_by_class.items()
for c in commands
]))
def get_class_command_names(self):
return sorted(
set(
[
"%s.%s" % (get_type_name(cls), str(c.name) if c.name != "new" else "__init__")
for cls, commands in self.command_defs_by_class.items()
for c in commands
]
)
)
def get_parameter_text(p):
description = indent(
p.doc)[4:] # indents, but grabs the first line's space back
if p.optional:
description = "(default=%s) " % (p.default if p.default is not None
else "None") + description
return ":param {name}: {description}\n:type {name}: {data_type}".format(
name=p.name,
description=description,
data_type=get_type_name(p.data_type))
def _get_returns_rst(return_info):
return """
:Returns:
: {data_type}
..
{description}
""".format(data_type=get_type_name(return_info.data_type), description=indent(return_info.doc, 8))
def _get_returns_rst(return_info):
return """
:Returns:
: {data_type}
..
{description}
""".format(data_type=get_type_name(return_info.data_type), description=indent(return_info.doc, 8))
def _get_parameter_rst(p):
data_type = get_type_name(p.data_type)
if p.optional:
data_type += " (default=%s)" % (p.default if p.default is not None else "None")
return """
**{name}** : {data_type}
..
{description}
""".format(name=p.name, data_type=data_type, description=indent(p.doc))
def get_big_tuples(self):
"""
Returns a tuple of strings: (The Python <class>.<name>, Command Def full name, side)
Side is 'client' if the api was defined 'clientside' or side is 'server' if the
command was completely generated by metaprogramming from info strictly from the server
If side is 'server', then the CommandDef full name may be used as is in the REST API.
"""
return sorted(set([("%s.%s" % (get_type_name(cls), str(c.name) if c.name != 'new' else '__init__'),
str(c.full_name),
self._get_side(c))
for cls, commands in self.command_defs_by_class.items() for c in commands]))
def get_big_tuples(self):
"""
Returns a tuple of strings: (The Python <class>.<name>, Command Def full name, side)
Side is 'client' if the api was defined 'clientside' or side is 'server' if the
command was completely generated by metaprogramming from info strictly from the server
If side is 'server', then the CommandDef full name may be used as is in the REST API.
"""
return sorted(set([("%s.%s" % (get_type_name(cls), str(c.name) if c.name != 'new' else '__init__'),
str(c.full_name),
self._get_side(c))
for cls, commands in self.command_defs_by_class.items() for c in commands]))
def _get_parameter_rst(p):
data_type = get_type_name(p.data_type)
if p.optional:
data_type += " (default=%s)" % (p.default if p.default is not None else "None")
return """
**{name}** : {data_type}
..
{description}
""".format(name=p.name, data_type=data_type, description=indent(p.doc))
def _get_argument_rest_rst(p):
data_type = get_type_name(p.data_type)
doc = p.doc or '<Missing Description>'
if p.optional:
data_type += " (default=%s)" % (p.default if p.default is not None else "None")
return """
**{name}** : {data_type}
..
{description}
""".format(name=p.name, data_type=data_type, description=indent(doc))
def get_return_data_type(json_schema):
"""get data type from return json schema"""
# by convention, if returning dict with a single 'value' value, then we extract it
if 'type' in json_schema and json_schema['type'] == 'object' and 'order' in json_schema and len(json_schema['order']) == 1 and json_schema['order'][0] == 'value':
return_type = _get_data_type(json_schema['properties']['value'])
type_name = get_type_name(return_type)
def _return_single_value_from_dict(result):
return result['value']
return AtkReturnType(type_name, _return_single_value_from_dict)
# otherwise, use regular get_data_type
return _get_data_type(json_schema)
def get_doc_stub_globals_text(module):
doc_stub_all = []
lines = []
return_types = set()
for key, value in sorted(module.__dict__.items()):
if _has_doc_stub_text(value):
doc_stub_text = _get_doc_stub_text(value)
if doc_stub_text:
doc_stub_all.append(key)
lines.append(doc_stub_text)
if hasattr(value, 'command'):
return_type = value.command.get_return_type()
if inspect.isclass(return_type):
return_types.add(return_type)
for return_type in return_types:
module_path = return_type.__module__
lines.insert(0, "from %s import %s" % (module_path, get_type_name(return_type)))
return '\n\n\n'.join(lines) if lines else '', doc_stub_all
def get_doc_stub_globals_text(module):
doc_stub_all = []
lines = []
return_types = set()
for key, value in sorted(module.__dict__.items()):
if _has_doc_stub_text(value):
doc_stub_text = _get_doc_stub_text(value)
if doc_stub_text:
doc_stub_all.append(key)
lines.append(doc_stub_text)
if hasattr(value, 'command'):
return_type = value.command.get_return_type()
if inspect.isclass(return_type):
return_types.add(return_type)
for return_type in return_types:
module_path = return_type.__module__
lines.insert(
0, "from %s import %s" % (module_path, get_type_name(return_type)))
return '\n\n\n'.join(lines) if lines else '', doc_stub_all
def get_returns_text(return_info, override_rtype):
description = indent(
return_info.doc)[4:] # indents, but grabs the first line's space back
return ":returns: {description}\n:rtype: {data_type}".format(
description=description,
data_type=get_type_name(override_rtype or return_info.data_type))
def get_parameter_text(p):
description = indent(p.doc)[4:] # indents, but grabs the first line's space back
if p.optional:
description = "(default=%s) " % (p.default if p.default is not None else "None") + description
return ":param {name}: {description}\n:type {name}: {data_type}".format(name=p.name,
description=description,
data_type=get_type_name(p.data_type))
def get_cls_init_rst_label(cls):
"""Gets the rst label (by our convention) for the init method so sphinx can create appropriate hyperlink"""
return "%s__init__" % get_type_name(cls)
def get_returns_text(return_info, override_rtype):
description = indent(return_info.doc)[4:] # indents, but grabs the first line's space back
return ":returns: {description}\n:rtype: {data_type}".format(description=description,
data_type=get_type_name(override_rtype
or return_info.data_type))
def get_cls_init_rst_label(cls):
"""Gets the rst label (by our convention) for the init method so sphinx can create appropriate hyperlink"""
return "%s__init__" % get_type_name(cls)
