def generate_integration_doc(input, output, examples, id_set, verbose=False):
try:
yml_data = get_yaml(input)
errors = []
example_dict = {}
if examples and os.path.isfile(examples):
command_examples = get_command_examples(examples)
example_dict, build_errors = build_example_dict(command_examples)
errors.extend(build_errors)
else:
errors.append(f'Command examples was not found {examples}.')
docs = [] # type: list
docs.extend(add_lines(yml_data.get('description')))
docs.append(
'This integration was integrated and tested with version xx of {}'.
format(yml_data['name']))
# Setup integration to work with Demisto
docs.extend(
generate_section(
'Configure {} on Demisto'.format(yml_data['name']), ''))
# Setup integration on Demisto
docs.extend(generate_setup_section(yml_data))
# Commands
command_section, command_errors = generate_commands_section(
yml_data, example_dict)
docs.extend(command_section)
errors.extend(command_errors)
# Additional info
docs.extend(generate_section('Additional Information', ''))
# Known limitations
docs.extend(generate_section('Known Limitations', ''))
doc_text = '\n'.join(docs)
save_output(output, 'README.md', doc_text)
if errors:
print_warning('Possible Errors:')
for error in errors:
print_warning(error)
except Exception as ex:
if verbose:
raise
else:
print_error(f'Error: {str(ex)}')
return
def generate_integration_doc(input_path: str,
examples: Optional[str] = None,
output: Optional[str] = None,
use_cases: Optional[str] = None,
permissions: Optional[str] = None,
command_permissions: Optional[str] = None,
limitations: Optional[str] = None,
insecure: bool = False,
verbose: bool = False,
command: Optional[str] = None):
""" Generate integration documentation.
Args:
input_path: path to the yaml integration
examples: path to the command examples
output: path to the output documentation
use_cases: use cases string
permissions: global permissions for the docs
command_permissions: permissions per command
limitations: limitations description
insecure: should use insecure
verbose: verbose (debug mode)
command: specific command to generate docs for
"""
try:
yml_data = get_yaml(input_path)
if not output: # default output dir will be the dir of the input file
output = os.path.dirname(os.path.realpath(input_path))
errors: list = []
example_dict = {}
if examples and os.path.isfile(examples):
command_examples = get_command_examples(examples)
example_dict, build_errors = build_example_dict(
command_examples, insecure)
errors.extend(build_errors)
else:
errors.append(f'Command examples was not found {examples}.')
if permissions == 'per-command':
command_permissions_dict: Any = {}
if command_permissions and os.path.isfile(command_permissions):
permission_list = get_command_permissions(command_permissions)
for command_permission in permission_list:
# get all the permissions after the command name
key, value = command_permission.split(" ", 1)
command_permissions_dict.update({key: value})
else:
errors.append(
f'Command permissions was not found {command_permissions}.'
)
else: # permissions in ['none', 'general']
command_permissions_dict = None
if command:
specific_commands = command.split(',')
readme_path = os.path.join(output, 'README.md')
with open(readme_path) as f:
doc_text = f.read()
for specific_command in specific_commands:
print(f'Generating docs for command `{command}`')
command_section, command_errors = generate_commands_section(
yml_data,
example_dict,
command_permissions_dict,
command=specific_command)
command_section_str = '\n'.join(command_section)
doc_text, err = append_or_replace_command_in_docs(
doc_text, command_section_str, specific_command)
errors.extend(err)
else:
docs = [] # type: list
docs.extend(add_lines(yml_data.get('description')))
docs.extend([
'This integration was integrated and tested with version xx of {}'
.format(yml_data['name'])
])
# Integration use cases
if use_cases:
docs.extend(generate_numbered_section('Use Cases', use_cases))
# Integration general permissions
if permissions == 'general':
docs.extend(generate_section('Permissions', ''))
# Setup integration to work with Demisto
docs.extend(
generate_section(
'Configure {} on Cortex XSOAR'.format(yml_data['name']),
''))
# Setup integration on Demisto
docs.extend(generate_setup_section(yml_data))
# Commands
command_section, command_errors = generate_commands_section(
yml_data,
example_dict,
command_permissions_dict,
command=command)
docs.extend(command_section)
errors.extend(command_errors)
# Known limitations
if limitations:
docs.extend(
generate_numbered_section('Known Limitations',
limitations))
doc_text = '\n'.join(docs)
save_output(output, 'README.md', doc_text)
if errors:
print_warning('Possible Errors:')
for error in errors:
print_warning(error)
except Exception as ex:
if verbose:
raise
else:
print_error(f'Error: {str(ex)}')
return
def generate_integration_doc(input, examples, output: str = None, use_cases: str = None,
permissions: str = None, command_permissions: str = None,
limitations: str = None, insecure: bool = False, verbose: bool = False):
try:
yml_data = get_yaml(input)
if not output: # default output dir will be the dir of the input file
output = os.path.dirname(os.path.realpath(input))
errors = []
example_dict = {}
if examples and os.path.isfile(examples):
command_examples = get_command_examples(examples)
example_dict, build_errors = build_example_dict(command_examples, insecure)
errors.extend(build_errors)
else:
errors.append(f'Command examples was not found {examples}.')
if permissions == 'per-command':
command_permissions_dict = {}
if command_permissions and os.path.isfile(command_permissions):
command_permissions = get_command_permissions(command_permissions)
for command_permission in command_permissions:
# get all the permissions after the command name
key, value = command_permission.split(" ", 1)
command_permissions_dict.update({key: value})
else:
errors.append(f'Command permissions was not found {command_permissions}.')
else: # permissions in ['none', 'general']
command_permissions_dict = None
docs = [] # type: list
docs.extend(add_lines(yml_data.get('description')))
docs.extend(['This integration was integrated and tested with version xx of {}'.format(yml_data['name'])])
# Integration use cases
if use_cases:
docs.extend(generate_numbered_section('Use Cases', use_cases))
# Integration general permissions
if permissions == 'general':
docs.extend(generate_section('Permissions', ''))
# Setup integration to work with Demisto
docs.extend(generate_section('Configure {} on Demisto'.format(yml_data['name']), ''))
# Setup integration on Demisto
docs.extend(generate_setup_section(yml_data))
# Commands
command_section, command_errors = generate_commands_section(yml_data, example_dict, command_permissions_dict)
docs.extend(command_section)
errors.extend(command_errors)
# Known limitations
if limitations:
docs.extend(generate_numbered_section('Known Limitations', limitations))
doc_text = '\n'.join(docs)
save_output(output, 'README.md', doc_text)
if errors:
print_warning('Possible Errors:')
for error in errors:
print_warning(error)
except Exception as ex:
if verbose:
raise
else:
print_error(f'Error: {str(ex)}')
return
def generate_integration_doc(input_path: str,
examples: Optional[str] = None,
output: Optional[str] = None,
use_cases: Optional[str] = None,
permissions: Optional[str] = None,
command_permissions: Optional[str] = None,
limitations: Optional[str] = None,
insecure: bool = False,
verbose: bool = False,
command: Optional[str] = None,
old_version: str = '',
skip_breaking_changes: bool = False,
is_contribution: bool = False):
""" Generate integration documentation.
Args:
input_path: path to the yaml integration
examples: path to the command examples
output: path to the output documentation
use_cases: use cases string
permissions: global permissions for the docs
command_permissions: permissions per command
limitations: limitations description
insecure: should use insecure
verbose: verbose (debug mode)
command: specific command to generate docs for
is_contribution: Check if the content item is a new integration contribution or not.
"""
try:
yml_data = get_yaml(input_path)
if not output: # default output dir will be the dir of the input file
output = os.path.dirname(os.path.realpath(input_path))
errors: list = []
example_dict: dict = {}
if examples:
specific_commands = command.split(',') if command else None
command_examples = get_command_examples(examples,
specific_commands)
example_dict, build_errors = build_example_dict(
command_examples, insecure)
errors.extend(build_errors)
else:
errors.append(f'Command examples was not found: {examples}.')
if permissions == 'per-command':
command_permissions_dict: Any = {}
if command_permissions and os.path.isfile(command_permissions):
permission_list = get_command_permissions(command_permissions)
for command_permission in permission_list:
# get all the permissions after the command name
key, value = command_permission.split(" ", 1)
command_permissions_dict.update({key: value})
else:
errors.append(
f'Command permissions was not found {command_permissions}.'
)
else: # permissions in ['none', 'general']
command_permissions_dict = None
if command:
specific_commands = command.split(',')
readme_path = os.path.join(output, 'README.md')
with open(readme_path) as f:
doc_text = f.read()
for specific_command in specific_commands:
print(f'Generating docs for command `{specific_command}`')
command_section, command_errors = generate_commands_section(
yml_data,
example_dict,
command_permissions_dict,
command=specific_command)
command_section_str = '\n'.join(command_section)
doc_text, err = append_or_replace_command_in_docs(
doc_text, command_section_str, specific_command)
errors.extend(err)
else:
docs = [] # type: list
docs.extend(add_lines(yml_data.get('description')))
if not is_contribution:
docs.extend([
'This integration was integrated and tested with version xx of {}'
.format(yml_data['name']), ''
])
# Checks if the integration is a new version
integration_version = re.findall("[vV][2-9]$",
yml_data.get("display", ""))
if integration_version and not skip_breaking_changes:
docs.extend([
'Some changes have been made that might affect your existing content. '
'\nIf you are upgrading from a previous of this integration, see [Breaking Changes]'
'(#breaking-changes-from-the-previous-version-of-this-integration-'
f'{yml_data.get("display", "").replace(" ", "-").lower()}).',
''
])
# Integration use cases
if use_cases:
docs.extend(generate_numbered_section('Use Cases', use_cases))
# Integration general permissions
if permissions == 'general':
docs.extend(generate_section('Permissions', ''))
# Setup integration to work with Demisto
docs.extend(
generate_section(
'Configure {} on Cortex XSOAR'.format(yml_data['display']),
''))
# Setup integration on Demisto
docs.extend(generate_setup_section(yml_data))
# Commands
command_section, command_errors = generate_commands_section(
yml_data,
example_dict,
command_permissions_dict,
command=command)
docs.extend(command_section)
# breaking changes
if integration_version and not skip_breaking_changes:
docs.extend(
generate_versions_differences_section(
input_path, old_version, yml_data.get("display", "")))
errors.extend(command_errors)
# Known limitations
if limitations:
docs.extend(
generate_numbered_section('Known Limitations',
limitations))
doc_text = '\n'.join(docs)
save_output(output, 'README.md', doc_text)
if errors:
print_warning('Possible Errors:')
for error in errors:
print_warning(error)
except Exception as ex:
if verbose:
raise
else:
print_error(f'Error: {str(ex)}')
return