@ibm-adw/skill-toolkit/starter-kit/src/generator/skill-documentation-generator.js

Developing your own skills with IBM Automation Digital Worker Skill Toolkit

/*
 Licensed Materials - Property of IBM
 5737-I23
 Copyright IBM Corp. 2019. All Rights Reserved.
 U.S. Government Users Restricted Rights:
 Use, duplication or disclosure restricted by GSA ADP Schedule
 Contract with IBM Corp.
 */

// TODO this is duplicated ! (base/skill-config.js & example/skill-config.js)
const inputSchemaExample = {
    '$schema': 'http://json-schema.org/draft-07/schema#',
    'title': 'Input schema for skill: Age Estimate',
    'type': 'object',
    'properties': {
        'name': {
            'description': 'The first name to be used to estimate the age',
            'type': 'string'
        },
        'countryId': {
            'description': 'The ID of the country (in ISO 3166-1 alpha-2 format) to be used to estimate the age, if you have not set the country in the configuration and you want to perform the estimate for a given country',
            'type': 'string'
        },
        'timeout': {
            'description': 'Timeout in milliseconds before canceling requests. This timeout is set by default to `5000` ms.',
            'type': 'integer',
            'default': 5000,
            'minimum': 0
        }
    },
    'required': [
        'name'
    ]
};

const outputSchemaExample = {
    '$schema': 'http://json-schema.org/draft-07/schema#',
    'title': 'Output schema for skill: Age Estimate',
    'type': 'object',
    'properties': {
        'name': {
            'description': 'The first name used to estimate the age',
            'type': 'string'
        },
        'age': {
            'description': 'The estimated age',
            'type': 'integer'
        },
        'count': {
            'description': 'The number of persons with the given first name who are used to estimate the age',
            'type': 'integer'
        },
        'countryId': {
            'description': 'The ID of the country (in ISO 3166-1 alpha-2 format) used to estimate the age if the estimate is performed for a given country',
            'type': 'string'
        }
    },
    'required': [
        'name',
        'age',
        'count'
    ]
};

const snippetSchemaExample = '// Snippet code to get and execute a skill\n' +
    'const skill = task.getSkill("<SKILL_NAME>");\n' +
    'const input = {\n' +
    '\tname: "Jane"\n' +
    '};\n' +
    'const result = await skill.execute(input);\n' +
    'task.context.logger.info(result);\n' +
    'return result;';

const inputSchemaBase = {
    '$schema': 'http://json-schema.org/draft-07/schema#',
    'title': 'Skill input schema'
};

const outputSchemaBase = {
    '$schema': 'http://json-schema.org/draft-07/schema#',
    'title': 'Skill output schema'
};

const snippetSchemaBase = '// Snippet code to get and execute a skill\n' +
    'const skill = task.getSkill("<SKILL_NAME>");\n' +
    'const result = await skill.execute(<SKILL_INPUT>);\n' +
    'task.context.logger.info(result);\n' +
    'return result;';

const generateDoc = (skillProjectRepo, skillData, sample) => {

    const inputSchema = (sample ? inputSchemaExample : inputSchemaBase);
    const outputSchema = (sample ? outputSchemaExample : outputSchemaBase);
    const snippet = (sample ? snippetSchemaExample : snippetSchemaBase);

    const { generateSpec } = require('./skill-spec-generator');
    const configSchema = generateSpec(skillData, sample)['config_schema'];

    return '# ' + skillProjectRepo + '\n' +
        '\n' +
        '### ' + skillData.name + ' - ' + skillData.packageName +
        '\n' +
        skillData.description +
        '\n\n' +
        'Author: ' + skillData.author +
        '\n' +
        'Category: ' + skillData.category +
        '\n\n' +
        'Level: ' + skillData.level +
        '\n\n' +

        '### Skill configuration\n' +
        'This is the configuration schema:\n' +
        '```json\n' +
        JSON.stringify(configSchema, null, 2) +
        '\n```\n' +
        '\n' +

        '### Skill input Schema\n' +
        '```json\n' +
        JSON.stringify(inputSchema, null, 2) +
        '\n```\n' +
        '\n' +

        '### Skill output Schema\n' +
        '```json\n' +
        JSON.stringify(outputSchema, null, 2) +
        '\n```\n' +
        '\n' +

        '### Code snippet\n' +
        '```json\n' +
        snippet +
        '\n```\n' +
        '\n';
};

module.exports = { generateDoc };