This issue outlines the specification for README and documentation generation.

Features

For this feature to be looked at as completed, the following must be implemented:

• Generate usage from task.json files
  • Task parser
  • Condition parser
  • Replaceable handler
  • Generated views
    • Table view
    • Usage view
• Support compiling multiple files to a single file
  • Asset handling
• New configuration schema for README generation
  • New validation schema
• New shared mapping configuration
  • New validation schema
  • New init command
• New root command

🚀 Usage generation

Scenario:

I have tasks that changes their input often. Having to update all the documentation is giving more work than necessary. I want to be able to specify a replaceable in my README files that will auto generate usage documentation based on the task.json file.

Replaceable

To allow the user to control where the usage documentation should be inserted we need an identifier that can be used multiple places.

Suggestion is a command format {{ #command[options] }} (inspired from Azure DevOps command logging)

Example for usage generation: {{ #usage[type=table;task=some-task]}}

Condition parser

Since task input can have conditions we should have a parser that is able to parse these conditions to give accurate documentation.

🚀 Multi file support

Scenario:

I have multiple tasks that each contains a README.md. When I publish my extensions I want all of these to be combined into a single README file. I want to be able to control the order of the inclusions.

Asset handling

README files might contain assets such as images. When copying and merging files we need a way to ensure asset files are moved to a correct location. The suggestion is to add a new configuration section that will map README files with their assets.

Example:

{
  // Location of the readme file
  "file": "./some-task/README.md",
  // Try by best effort to replace asset links after moving assets
  "resolveAssetLinks": true,
  // Assets for this README file
  "assets": [
    {
      // Where the asset is stored
      "source": "./some-task/images/*",
      // Where the asset should be stored after merge.
      // [output] is a variable that contains the output location of the README file and
      // will be replaced by the command.
      "dest": "[output]/images"
    },
    {
      "source": "./some-task/docs/image1.png",
      "dest": "[output]/images"
    }
  ]
}

🚀 Shared mapping configuration

Multiple planned commands will need the same task mapping scheme. Therefor we should introduce a new global mapping configuration to store this in.

Currently the mapping only needs to include a key/value mapping between a task key and the location of the task.json file.

{
  "tasks": {
    "build": "../tasks/build-task/task.json",
    "analyse": "../tasks/analyse/task.json"
  }
}

This file should be stored as .azext/mappings.json

Commands

This feature introduces a new set of commands

• azext docs help
• azext docs new config
• azext docs generate