generate-docs

Generate README documentation for Cortex XSOAR integrations, scripts, and playbooks.

Generates a README file for your integration, script or playbook. Used to create documentation files for Cortex XSOAR.

Note

This command is not supported in Cortex XSIAM.

This command creates a new README.md file in the same directory as the entity on which it ran, unless otherwise specified using the -o flag. To generate command examples, set up the required environment variables prior to running this command in order to establish a connection between the Demisto SDK and the server, as well as create a file containing command examples to be run for the documentation.

Arguments

-i, --input	Path of the YAML file.
-o, --output	The output directory to write the documentation file to. Documentation file name is README.md. If not specified, written to the YAML directory.
-uc, --use_cases	For integrations - provide a list of use cases that should appear in the generated docs. Create an unordered list by using * before each use-case. For example: *Add indicators to allow list / block list *Calculate DBot Score for indicators.
-c, --command	A comma-separated list of command names to generate documentation for. The rest of the commands are ignored. For example, xdr-get-incidents,xdr-update-incident.
-e, --examples	For integrations: The path for a file containing examples. Each command should be in a separate line or a comma-separated list of commands. For scripts: The script example surrounded by single quotes. For example: -e '!ConvertFile entry_id=<entry_id>'.
-p, --permissions	The required permissions.
-cp, --command-permissions	Path for file containing command permissions. Each command permissions should be in a separate line. For example, command-name Administrator READ-WRITE.
-l, --limitations	Known limitations. Create an unordered list by using * before each limitation. Examples: *This integration does not support the lifecycle countermeasures. *Custom fields cannot be created through this integration, but custom fields created on RTIR can be filled when creating a new ticket.
--insecure	Skips certificate validation.
--old-version	Path of the old integration version YAML file.
--skip-breaking-changes	Do not generate the breaking changes section.
-gr/-ngr, --graph/--no-graph	Whether to use the content graph.
-f, --force	Whether to force the generation of documentation (rather than update when it exists in version control).
--custom-image-path	A custom path to a playbook image. If not specified, a default link will be added to the file.
-rt, --readme-template	The readme template that should be appended to the given README.md file. Possible values are syslog, xdrc, http-collector.

Notes

• If command_permissions are not provided, a generic message regarding the need for permissions is given.

• If no output is provided, the README.md file is generated in the input file repository.

• If no additionalinfo is provided for a commonly used parameter (for example, API Key), a matching default value is used, see the parameters and defaults in default_additional_information.json.

• To generate an incident mirroring section, verify the isremotesyncin and/or isremotesyncout parameters are set to true in the YAML file. In addition, the following configuration parameters (if used) should be named as stated:

  • incidents_fetch_query

  • mirroring tags - available names are comment_tag, work_notes_tag and file_tag.

  • mirror_direction

  • close_incident

  • close_out (opposite of close_incident)

• If the integration/script/playbook exists in version control, the version from the main branch (the master) will be used to only render the modified sections (for example configuration, commands) unless the --force flag is specified.

Examples

• demisto-sdk generate-docs -i Packs/MyPack/Integrations/MyInt/MyInt.yml -e Packs/MyPack/Integrations/MyInt/command_example.txt

  Generates for the MyInt integration using the command examples found in the .txt file in the MyInt integration.

• demisto-sdk generate-docs -i Packs/MyPack/Integrations/MyInt/MyInt_v2.yml --old-version Packs/MyPack/Integrations/MyInt/MyInt.yml

  Generates documentation for the MyInt_v2 integration including a section about changes compared the MyInt integration. The command automatically detects if the given integration is a v2 using the integration's display name and creates the changes section. If no --old-version is supplied a prompt appears asking for the path to the old integration.