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

When an operation fails, it is some places thrown as an error and just logged other places. All errors/issues should be handled the same way and throw proper errors with exit codes.

Add count to tag headers

With counter

### 🚀 Features (4)

Without counter

### 🚀 Features

Replaceable: {{ changeCount }}

• Add replaceable to generator

{
  "publishDate": "01-01-1970",
  "version": "0.0.0",
  "notes": "Optional notes",
  "summary": "Optional summary",
  "banner": {
      "type": "info", // Info - Warning - Error
      "message": "Some message"
  },
  "modules": [
    {
      "name": "module-name",
      "version": "0.0.0",
      "changes": [
        {
          "description": "Some change description",
          "type": "feature",
          "issue": 0,
          "pullRequest": 0
        }
      ]
    }
  ]
}

Renders

When a single contributor contributes more than once in a release, they are duplicated in the list

Issue

Add a new change with only a linked PR

{
    "publishDate": "2021-12-22",
    "version": "0.2.1",
    "modules": [
      {
        "name": "core",
        "version": "0.2.1",
        "changes": [
          {
            "type": "docs",
            "description": "Updated NPM readme",
            "pullRequest": 20
          }
        ]
      }
    ]
  },

Generated changelog:

# Changelog

## 0.2.1 (2021-12-22)

### 📝 Documentation (1)

#### `[email protected]`

- Updated NPM readme
  - Issue: [GH#20 - Fix readme for Npm](https://github.com/joachimdalen/azext/pull/20)

Should be:

# Changelog

## 0.2.1 (2021-12-22)

### 📝 Documentation (1)

#### `[email protected]`

- Updated NPM readme
  - PR: [GH#20 - Fix readme for Npm](https://github.com/joachimdalen/azext/pull/20)

Broken line: https://github.com/joachimdalen/azext/blob/master/src/modules/changelog/generator.ts#L212

Actual Behaviour

azext init --root rootfolder and azext init will both create the .azext folder in the current working directory

Expected Behaviour

• azext init --root rootfolder will create the .azext folder in a sub folder called rootfolder
• azext init will create the .azext folder in the current working directory

Generated example:

- task: AzExt [email protected]
  inputs:
    command: generate
    output: CHANGELOG.md
    configName: changelog-config.json

• Should only use Major version
• Should use name instead of friendlyName for title

Running azext init in a new folder produces the error Error: Failed to find configuration folder in working directory

Short summary of the issue

When adding a change type without a mapping, changelog generation fails

Mapping file

 "typeMapping": {
    "feature": ":rocket: Features",
    "fix": ":bug: Fixes",
    "tests": ":test_tube: Tests",
    "other": ":speech_balloon: Other",
    "docs": ":memo: Documentation"
  },

Changelog entry

 {
        "version": "0.0.x",
        "name": "some-module",
        "changes": [
          {
            "type": "feat",
            "description": "Added  feat"
          }
        ]
      }

Error

No mapping found for change type feat
TypeError: Cannot read properties of undefined (reading 'replace')

azext changelog new -o changelog-prod.json is throwing TypeError: Cannot read properties of undefined (reading 'includes')

This is caused by a mismatch in the cli options mapping

This issue outlines the specification for manifest generation from partial manifests

TODO