Example Usage Templates

[natescherer]

Wanted to get some thoughts about maybe adding templates for the Example Usage section, similar to the use of NOTES.md. As it stands now, this action overwrites the Example Usage section each time it runs, which is less than ideal.

I was thinking maybe an EXAMPLES.json file like the following:

{
    "optionSets": [
        {
            "optionOne": "valueOne"
        },
        {
            "optionTwo": "valueTwo"
        }
    ]
}

If this seems agreeable, I could cook up a PR for this, I think.

[joshspicer]

That seems super reasonable, thanks for offering to contribute it!

Given the current auto-generated example:

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {}
}

I agree that some file (EXAMPLES.json) could look something like:

[
  "With a version": {
     "version": "1.0.0"
  },
  "With a version and password": {
     "version": "1.0.0",
     "password": "vscode"
  },

]

...To then generate markdown like:

---

Example Usage

With a version

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {
       "version": "1.0.0"
    }
}

With a version and password

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {
       "version": "1.0.0",
       "password": "vscode"
    }
}

[joshspicer]

I've also tossed around the idea of putting all of a Feature's default options into the value object, but landed on the empty object for copy/paste simplicity. Effectively, putting all options at the default value resolves to exactly the same as placing nothing.

That said, I like your idea of giving the author the choice. (Could be cool to do some simple validation on the output to ensure those options exist in the devcontainer-feature.json)