Add asset handling and fix minor changelog issue (#46)

.azext/changelog-cache.json

@@ -93,6 +93,13 @@
     }
   ],
   "pullRequests": [
+    {
+      "id": 858418927,
+      "number": 46,
+      "submitter": "joachimdalen",
+      "title": "Add asset handling and fix minor changelog issue",
+      "url": "https://github.com/joachimdalen/azext/pull/46"
+    },
     {
       "id": 835470580,
       "number": 45,

.azext/changelog.json

@@ -13,6 +13,23 @@
             "description": "Process replacement commands in partial files",
             "issue": 30,
             "pullRequest": 45
+          },
+          {
+            "type": "feature",
+            "description": "Added asset handling for images to support multiple documentation displays",
+            "issue": 3,
+            "pullRequest": 46
+          }
+        ]
+      },
+      {
+        "name": "changelog",
+        "version": "0.6.0",
+        "changes": [
+          {
+            "type": "fix",
+            "description": "Fixed extra splitting line added for the first version",
+            "pullRequest": 46
           }
         ]
       }

.azext/readme.json

@@ -21,5 +21,16 @@
     "task-two-readme": {
       "file": "../testdata/task2/README.md"
     }
-  }
+  },
+  "profiles": [
+    {
+      "name": "github",
+      "imageFolder": "docs/images",
+      "relative": true
+    },
+    {
+      "name": "marketplace",
+      "imageFolder": "marketplace/images"
+    }
+  ]
 }

CHANGELOG.md

@@ -2,14 +2,26 @@
 
 ## 0.6.0 (2022-01-XX)
 
-### 🚀 Features (1)
+### 🚀 Features (2)
 
 #### `[email protected]`
 
 - Process replacement commands in partial files
+
   - Suggested in [GH#30 - Process replacement commands in partial files](https://github.com/joachimdalen/azext/issues/30)
   - Added in [PR#45 - Process replacement commands in partial files](https://github.com/joachimdalen/azext/pull/45)
 
+- Added asset handling for images to support multiple documentation displays
+  - Suggested in [GH#3 - Documentation generation](https://github.com/joachimdalen/azext/issues/3)
+  - Added in [PR#46 - Add asset handling and fix minor changelog issue](https://github.com/joachimdalen/azext/pull/46)
+
+### 🐛 Fixes (1)
+
+#### `[email protected]`
+
+- Fixed extra splitting line added for the first version
+  - Fixed in [PR#46 - Add asset handling and fix minor changelog issue](https://github.com/joachimdalen/azext/pull/46)
+
 ---
 
 ## 0.5.0 (2022-01-16)
@@ -98,18 +110,6 @@
 
 ## 0.2.2 (2021-12-26)
 
-### 💬 Other (2)
-
-#### `[email protected]`
-
-- Refactor how cli parameters are set in the cli definition
-  - Pull Request: [PR#25 - Fix wrong option names being passed from cli to handler](https://github.com/joachimdalen/azext/pull/25)
-
-#### `[email protected]`
-
-- Refactor how cli parameters are set in the cli definition
-  - Pull Request: [PR#25 - Fix wrong option names being passed from cli to handler](https://github.com/joachimdalen/azext/pull/25)
-
 ### 🐛 Fixes (3)
 
 #### `[email protected]`
@@ -129,6 +129,18 @@
   - Reported in [GH#21 - Can not initialize in a new project](https://github.com/joachimdalen/azext/issues/21)
   - Fixed in [PR#26 - Fix not being able to initialize in a new project](https://github.com/joachimdalen/azext/pull/26)
 
+### 💬 Other (2)
+
+#### `[email protected]`
+
+- Refactor how cli parameters are set in the cli definition
+  - Pull Request: [PR#25 - Fix wrong option names being passed from cli to handler](https://github.com/joachimdalen/azext/pull/25)
+
+#### `[email protected]`
+
+- Refactor how cli parameters are set in the cli definition
+  - Pull Request: [PR#25 - Fix wrong option names being passed from cli to handler](https://github.com/joachimdalen/azext/pull/25)
+
 ---
 
 ## 0.2.1 (2021-12-25)

docs/readme/commands.md

@@ -8,6 +8,7 @@ Supported commands:
 
 - [Task Input](#task-input)
 - [Task Field](#task-field)
+- [Include Image](#include-image)
 
 ## Task Input
 
@@ -71,7 +72,7 @@ The task fild command parses your `task.json` and extracts data.
 | task         | Key of task defined in `mapping.json`                             |
 | field        | The field to fetch data from                                      |
 | objectHandle | How to handle objects. Valid options are `json` and `json-pretty` |
-| coreFormat   | Wraps the field in a code block                                   |
+| codeFormat   | Wraps the field in a code block                                   |
 
 ## Example
 
@@ -80,3 +81,33 @@ Version: {{ #task-input[task=demo-task;field=version] }}
 ```
 
 Version: 0.3.3
+
+## Include Image
+
+The command allows you to include images that might be located in different places for different files, such as one location for documentation on GitHub and another one located in your extension.
+
+This requires the profile to be set in `readme.json`.
+
+```json
+"profiles": [
+  {
+    "name": "github",
+    "imageFolder": "docs/images",
+    "relative": true
+  },
+  {
+    "name": "marketplace",
+    "imageFolder": "marketplace/images"
+  }
+]
+```
+
+**Command:** `include-image`
+
+| Parameter | Description                                             |
+| --------- | ------------------------------------------------------- |
+| imagePath | Relative path to your image based on the profile folder |
+
+```md
+{{ #include-image[imagePath=azext-icon.png] }}
+```

docs/readme/generate.md

@@ -24,8 +24,9 @@ Command List
 
 Options
 
-  --input string    Input file containing the template
-  --output string   Output file to write replaced value to
+  --input string     Input file containing the template
+  --output string    Output file to write replaced value to
+  --profile string   Image profile to handle file paths
 
 Global Options
 

package.json

@@ -23,7 +23,7 @@
     "test:coverage": "jest --coverage",
     "test:ci": "jest --coverage --ci",
     "build:docs": "cd scripts && ts-node readme-generation.ts && cd ..",
-    "build:demo-docs": "node ./dist/azext.js readme generate --input ./testdata/demo-readme.md --output ./testdata/demo-readme-replaced.md",
+    "build:demo-docs": "node ./dist/azext.js readme generate --input ./testdata/demo-readme.md --output ./testdata/demo-readme-replaced.md --profile github",
     "build:demo-task-docs": "node ./dist/azext.js readme generate --input ./testdata/README.md --output ./testdata/README-GEN.md",
     "lint": "eslint src --ignore-path .eslintignore --ext ts",
     "lint:fix": "eslint src --fix --ignore-path .eslintignore --ext ts"

schemas/v1/readme-schema.json

@@ -52,6 +52,25 @@
           "required": ["file"]
         }
       }
+    },
+    "profiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "imageFolder": {
+            "type": "string"
+          },
+          "relative": {
+            "type": "boolean"
+          }
+        },
+        "required": ["name", "imageFolder"]
+      }
     }
   }
 }

src/cli/readme/handlers/readme-cmd-handler.ts

@@ -15,7 +15,7 @@ export default class ReadmeCmdHandler extends BaseCommandHandler<ReadmeOptions>
     this._configProvider = new ConfigProvider();
   }
   async handleCommand(options: ReadmeOptions): Promise<void> {
-    const res = await this._service.processReadMe(options.input);
+    const res = await this._service.processReadMe(options);
 
     const fullOutputPath = this._configProvider.getFullFilePath(options.output);
     await fs.writeFile(fullOutputPath, res);

src/cli/readme/readme-definition.ts

@@ -8,7 +8,8 @@ import ReadmeInitCmdHandler from './handlers/readme-init-cmd-handler';
 
 enum ReadmeOptionNames {
   Input = 'input',
-  Output = 'output'
+  Output = 'output',
+  Profile = 'profile'
 }
 
 const readmeCommands: CommandBase = {
@@ -61,13 +62,18 @@ const readmeCommands: CommandBase = {
             {
               name: ReadmeOptionNames.Output,
               description: 'Output file to write replaced value to'
+            },
+            {
+              name: ReadmeOptionNames.Profile,
+              description: 'Image profile to handle file paths'
             }
           ]
         }
       ],
       options: [
         { name: ReadmeOptionNames.Input, alias: 'i' },
-        { name: ReadmeOptionNames.Output, alias: 'o' }
+        { name: ReadmeOptionNames.Output, alias: 'o' },
+        { name: ReadmeOptionNames.Profile, alias: 'p' }
       ],
       subCommands: [defaultHelpCommand]
     },

src/core/utils.ts

@@ -10,7 +10,7 @@ export const isIssue = (item: GitHubIssue | undefined): item is GitHubIssue => {
   return !!item;
 };
 
-export const distinct = (value: any, index: number, self: any[]) => {
+export const distinct = <T>(value: T, index: number, self: T[]) => {
   return self.indexOf(value) === index;
 };
 

src/modules/changelog/generator.ts

@@ -494,7 +494,6 @@ class Generator {
     }
 
     this.addContributors(builder, cfg, release, context);
-    builder.addSplitter();
   }
 
   buildFile(context: GeneratorContext, logs: ChangelogDefinition[]): string {
@@ -511,6 +510,10 @@ class Generator {
 
     for (const version of logs) {
       this.addVersion(builder, cfg, version, context);
+
+      if (logs.indexOf(version) !== logs.length) {
+        builder.addSplitter();
+      }
     }
     return builder.get();
   }

src/modules/readme/command-service.ts

@@ -59,7 +59,7 @@ export default class CommandService {
   }
 
   getCommandParameters(parameters: string, command: ReplacementCommand) {
-    const exp = /(?<param>[a-zA-Z0-9-_]+.)=(?<val>[a-zA-Z0-9-_]+.)/g;
+    const exp = /(?<param>[a-zA-Z0-9-_]+.)=(?<val>[a-zA-Z0-9-_\\.]+.)/g;
     let m;
 
     const parsedGroups: { [key: string]: string }[] = [];
@@ -74,7 +74,6 @@ export default class CommandService {
     }
 
     const options: { [key: string]: string | undefined } = {};
-
     for (const opt of command.options) {
       const param = parsedGroups.find((p) => p.param === opt.name);
 

src/modules/readme/formatters/include-file-formatter.ts

@@ -3,7 +3,9 @@ import { EOL } from 'os';
 
 import ConfigProvider from '../../../data-providers/config-provider';
 import { ReadmeConfig } from '../models';
-import ReplacementCommandFormatter from '../models/replacement-command-formatter';
+import ReplacementCommandFormatter, {
+  ReplacementOptions
+} from '../models/replacement-command-formatter';
 import TaskService from '../task-service';
 
 export interface IncludeFileFormatterOptions {
@@ -19,7 +21,9 @@ export default class IncludeFileFormatter extends ReplacementCommandFormatter<In
     this._service = new TaskService();
     this._configProvider = new ConfigProvider();
   }
-  async getFormatted(options: IncludeFileFormatterOptions): Promise<any> {
+  async getFormatted(
+    options: ReplacementOptions<IncludeFileFormatterOptions>
+  ): Promise<any> {
     if (options.file === undefined) {
       throw new Error('Missing required properties: file');
     }

src/modules/readme/formatters/include-image-formatter.ts

@@ -0,0 +1,54 @@
+import path from 'path';
+
+import ReplacementCommandFormatter, {
+  ReplacementOptions
+} from '../models/replacement-command-formatter';
+import TaskService from '../task-service';
+
+export interface IncludeImageFormatterOptions {
+  imagePath: string;
+  profile?: string;
+}
+
+export default class IncludeImageFormatter extends ReplacementCommandFormatter<IncludeImageFormatterOptions> {
+  private _service: TaskService;
+
+  constructor() {
+    super();
+    this._service = new TaskService();
+  }
+  async getFormatted(
+    options: ReplacementOptions<IncludeImageFormatterOptions>
+  ): Promise<any> {
+    if (options.profile === undefined) {
+      throw new Error('A profile is required. Set with --profile');
+    }
+
+    const config = await this._service.getReadMeConfig();
+
+    if (config) {
+      const profile = config.profiles?.find((x) => x.name === options.profile);
+
+      if (profile === undefined) {
+        throw new Error('No such profile ' + options.profile);
+      }
+
+      const imgPath = path.join(profile.imageFolder, options.imagePath);
+
+      const imagePath = profile.relative
+        ? path.join(
+            path.relative(
+              path.resolve(path.dirname(options.input)),
+              path.resolve(path.dirname(imgPath))
+            ),
+            path.basename(options.imagePath)
+          )
+        : imgPath;
+
+      const img = `![${options.imagePath}](${imagePath})`;
+      return img;
+    }
+
+    return undefined;
+  }
+}