def generate_playbook_doc(input, output, examples, id_set, verbose=False):
try:
playbook = get_yaml(input)
errors = []
description = playbook.get('description', '')
if not description:
errors.append('Error! You are missing description for the playbook')
doc = [description, '', '## Dependencies',
'This playbook uses the following sub-playbooks, integrations, and scripts.', '']
playbooks, integrations, scripts, commands = get_playbook_dependencies(playbook)
inputs, inputs_errors = get_inputs(playbook)
outputs, outputs_errors = get_outputs(playbook)
errors.extend(inputs_errors)
errors.extend(outputs_errors)
doc.extend(generate_list_section('Sub-playbooks', playbooks, header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any sub-playbooks.'))
doc.extend(generate_list_section('Integrations', integrations, header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any integrations.'))
doc.extend(generate_list_section('Scripts', scripts, header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any scripts.'))
doc.extend(generate_list_section('Commands', commands, header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any commands.'))
doc.extend(generate_table_section(inputs, 'Playbook Inputs', 'There are no inputs for this playbook.'))
doc.extend(generate_table_section(outputs, 'Playbook Outputs', 'There are no outputs for this playbook.'))
doc.append('<!-- Playbook PNG image comes here -->')
doc_text = '\n'.join(doc)
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 test_generate_list_section():
from demisto_sdk.commands.generate_docs.common import generate_list_section
section = generate_list_section('Inputs', ['item1', 'item2'], False,
'No inputs found.')
expected_section = ['## Inputs', '* item1', '* item2', '']
assert section == expected_section
def test_generate_list_section_empty():
from demisto_sdk.commands.generate_docs.common import generate_list_section
section = generate_list_section('Inputs', [],
empty_message='No inputs found.')
expected_section = ['## Inputs', 'No inputs found.', '']
assert section == expected_section
def test_generate_list_with_text_section():
from demisto_sdk.commands.generate_docs.common import generate_list_section
section = generate_list_section('Inputs', ['item1', 'item2'], True, 'No inputs found.', 'some text')
expected_section = [
'## Inputs', '---', 'some text', '* item1', '* item2', '']
assert section == expected_section
def generate_script_doc(input_path,
examples,
output: str = None,
permissions: str = None,
limitations: str = None,
insecure: bool = False,
verbose: bool = False):
try:
doc: list = []
errors: list = []
example_section: list = []
if not output: # default output dir will be the dir of the input file
output = os.path.dirname(os.path.realpath(input_path))
if examples:
if os.path.isfile(examples):
with open(examples, 'r') as examples_file:
examples = examples_file.read().splitlines()
else:
examples = examples.split(',')
for i, example in enumerate(examples):
if not example.startswith('!'):
examples[i] = f'!{examples}'
example_dict, build_errors = build_example_dict(examples, insecure)
script_name = list(
example_dict.keys())[0] if example_dict else None
example_section, example_errors = generate_script_example(
script_name, example_dict)
errors.extend(build_errors)
errors.extend(example_errors)
else:
errors.append(
'Note: Script example was not provided. For a more complete documentation,run with the -e '
'option with an example command. For example: -e "!ConvertFile entry_id=<entry_id>".'
)
script = get_yaml(input_path)
# get script data
script_info = get_script_info(input_path)
script_id = script.get('commonfields')['id']
# get script dependencies
dependencies, _ = get_depends_on(script)
# get the script usages by the id set
if not os.path.isfile(DEFAULT_ID_SET_PATH):
id_set_creator = IDSetCreator(output='', print_logs=False)
id_set, _, _ = id_set_creator.create_id_set()
else:
id_set = open_id_set_file(DEFAULT_ID_SET_PATH)
used_in = get_used_in(id_set, script_id)
description = script.get('comment', '')
# get inputs/outputs
inputs, inputs_errors = get_inputs(script)
outputs, outputs_errors = get_outputs(script)
errors.extend(inputs_errors)
errors.extend(outputs_errors)
if not description:
errors.append(
'Error! You are missing a description for the Script')
doc.append(description + '\n')
doc.extend(generate_table_section(script_info, 'Script Data'))
if dependencies:
doc.extend(
generate_list_section(
'Dependencies',
dependencies,
True,
text='This script uses the following commands and scripts.'
))
# Script global permissions
if permissions == 'general':
doc.extend(generate_section('Permissions', ''))
if used_in:
if len(used_in) <= 10:
doc.extend(
generate_list_section(
'Used In',
used_in,
True,
text=
'This script is used in the following playbooks and scripts.'
))
else: # if we have more than 10 use a sample
print_warning(
f'"Used In" section found too many scripts/playbooks ({len(used_in)}). Will use a sample of 10.'
' Full list is available as a comment in the README file.')
sample_used_in = random.sample(used_in, 10)
doc.extend(
generate_list_section(
'Used In',
sorted(sample_used_in),
True,
text=
'Sample usage of this script can be found in the following playbooks and scripts.'
))
used_in_str = '\n'.join(used_in)
doc.append(
f"<!--\nUsed In: list was truncated. Full list commented out for reference:\n\n{used_in_str}\n -->\n"
)
doc.extend(
generate_table_section(inputs, 'Inputs',
'There are no inputs for this script.'))
doc.extend(
generate_table_section(outputs, 'Outputs',
'There are no outputs for this script.'))
if example_section:
doc.extend(example_section)
# Known limitations
if limitations:
doc.extend(
generate_numbered_section('Known Limitations', limitations))
doc_text = '\n'.join(doc)
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_playbook_doc(input,
output: str = None,
permissions: str = None,
limitations: str = None,
verbose: bool = False):
try:
playbook = 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 = []
description = playbook.get('description', '')
_name = playbook.get('name', 'Unknown')
if not description:
errors.append(
'Error! You are missing description for the playbook')
doc = [
description, '', '## Dependencies',
'This playbook uses the following sub-playbooks, integrations, and scripts.',
''
]
playbooks, integrations, scripts, commands = get_playbook_dependencies(
playbook, input)
inputs, inputs_errors = get_inputs(playbook)
outputs, outputs_errors = get_outputs(playbook)
playbook_filename = os.path.basename(input).replace('.yml', '')
errors.extend(inputs_errors)
errors.extend(outputs_errors)
# Playbooks general permissions
if permissions == 'general':
doc.extend(generate_section('Permissions', ''))
doc.extend(
generate_list_section(
'Sub-playbooks',
playbooks,
header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any sub-playbooks.'))
doc.extend(
generate_list_section(
'Integrations',
integrations,
header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any integrations.'))
doc.extend(
generate_list_section(
'Scripts',
scripts,
header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any scripts.'))
doc.extend(
generate_list_section(
'Commands',
commands,
header_type=HEADER_TYPE.H3,
empty_message='This playbook does not use any commands.'))
doc.extend(
generate_table_section(inputs, 'Playbook Inputs',
'There are no inputs for this playbook.'))
doc.extend(
generate_table_section(outputs, 'Playbook Outputs',
'There are no outputs for this playbook.'))
# Known limitations
if limitations:
doc.extend(
generate_numbered_section('Known Limitations', limitations))
doc.append('## Playbook Image\n---')
doc.append(f'')
doc_text = '\n'.join(doc)
save_output(output, f'{playbook_filename}_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_script_doc(input, output, examples, id_set='', verbose=False):
try:
doc = []
errors = []
used_in = []
example_section = []
if examples:
if not examples.startswith('!'):
examples = f'!{examples}'
example_dict, build_errors = build_example_dict([examples])
script_name = examples.split(' ')[0][1:]
example_section, example_errors = generate_script_example(
script_name, example_dict)
errors.extend(build_errors)
errors.extend(example_errors)
else:
errors.append(
f'Note: Script example was not provided. For a more complete documentation,run with the -e '
f'option with an example command. For example: -e "!ConvertFile entry_id=<entry_id>".'
)
script = get_yaml(input)
# get script data
secript_info = get_script_info(input)
script_id = script.get('commonfields')['id']
# get script dependencies
dependencies, _ = get_depends_on(script)
if not id_set:
errors.append(f'id_set.json file is missing')
elif not os.path.isfile(id_set):
errors.append(f'id_set.json file {id_set} was not found')
else:
used_in = get_used_in(id_set, script_id)
description = script.get('comment', '')
deprecated = script.get('deprecated', False)
# get inputs/outputs
inputs, inputs_errors = get_inputs(script)
outputs, outputs_errors = get_outputs(script)
errors.extend(inputs_errors)
errors.extend(outputs_errors)
if not description:
errors.append(
'Error! You are missing description for the playbook')
if deprecated:
doc.append('`Deprecated`')
doc.append(description)
doc.extend(generate_table_section(secript_info, 'Script Data'))
if dependencies:
doc.extend(
generate_list_section(
'Dependencies',
dependencies,
True,
text='This script uses the following commands and scripts.'
))
if used_in:
doc.extend(
generate_list_section(
'Used In',
used_in,
True,
text=
'This script is used in the following playbooks and scripts.'
))
doc.extend(
generate_table_section(inputs, 'Inputs',
'There are no inputs for this script.'))
doc.extend(
generate_table_section(outputs, 'Outputs',
'There are no outputs for this script.'))
if example_section:
doc.extend(example_section)
doc_text = '\n'.join(doc)
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_script_doc(input,
examples,
output: str = None,
permissions: str = None,
limitations: str = None,
insecure: bool = False,
verbose: bool = False):
try:
doc = []
errors = []
used_in = []
example_section = []
if not output: # default output dir will be the dir of the input file
output = os.path.dirname(os.path.realpath(input))
if examples:
if not examples.startswith('!'):
examples = f'!{examples}'
example_dict, build_errors = build_example_dict([examples],
insecure)
script_name = examples.split(' ')[0][1:]
example_section, example_errors = generate_script_example(
script_name, example_dict)
errors.extend(build_errors)
errors.extend(example_errors)
else:
errors.append(
f'Note: Script example was not provided. For a more complete documentation,run with the -e '
f'option with an example command. For example: -e "!ConvertFile entry_id=<entry_id>".'
)
script = get_yaml(input)
# get script data
secript_info = get_script_info(input)
script_id = script.get('commonfields')['id']
# get script dependencies
dependencies, _ = get_depends_on(script)
# get the script usages by the id set
id_set_creator = IDSetCreator()
id_set = id_set_creator.create_id_set()
used_in = get_used_in(id_set, script_id)
description = script.get('comment', '')
deprecated = script.get('deprecated', False)
# get inputs/outputs
inputs, inputs_errors = get_inputs(script)
outputs, outputs_errors = get_outputs(script)
errors.extend(inputs_errors)
errors.extend(outputs_errors)
if not description:
errors.append(
'Error! You are missing description for the playbook')
if deprecated:
doc.append('`Deprecated`')
doc.append(description)
doc.extend(generate_table_section(secript_info, 'Script Data'))
if dependencies:
doc.extend(
generate_list_section(
'Dependencies',
dependencies,
True,
text='This script uses the following commands and scripts.'
))
# Script global permissions
if permissions == 'general':
doc.extend(generate_section('Permissions', ''))
if used_in:
doc.extend(
generate_list_section(
'Used In',
used_in,
True,
text=
'This script is used in the following playbooks and scripts.'
))
doc.extend(
generate_table_section(inputs, 'Inputs',
'There are no inputs for this script.'))
doc.extend(
generate_table_section(outputs, 'Outputs',
'There are no outputs for this script.'))
if example_section:
doc.extend(example_section)
# Known limitations
if limitations:
doc.extend(
generate_numbered_section('Known Limitations', limitations))
doc_text = '\n'.join(doc)
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
