updated development.md to cater for devcontainers and multi-platform development

Author: RenSilvaAU

docs/development.md

@@ -1,78 +1,126 @@
 # AutoRest PowerShell Generator - Development
 
-## Requirements
+## Getting Started with Dev Containers (Recommended)
 
-Use of this project requires the following:
+The easiest way to get started is using the provided Dev Container configuration, which automatically sets up all required tools and dependencies.
 
-- [NodeJS LTS](https://nodejs.org) (currently 14.15.5) <br> I recommend that you use a tool like [nvs](https://github.com/jasongin/nvs) so that you can switch between versions of node without pain <br>&nbsp;
-- [AutoRest](https://aka.ms/autorest) v3 <br> `npm install -g autorest@latest ` <br>&nbsp;
-- [RushJS](https://rushjs.io/) manages multiple nodejs projects in a single repository. <br> `npm install -g @microsoft/rush` <br>&nbsp;
-- PowerShell 6.0 - If you dont have it installed, you can use the cross-platform npm package <br> `npm install -g pwsh` <br>&nbsp;
-- Dotnet SDK 2 or greater - If you dont have it installed, you can use the cross-platform npm package <br> `npm install -g dotnet-sdk-2.1 ` <br>&nbsp;
-- _Recommended_: [Visual Studio Code](https://code.visualstudio.com/)
+### Prerequisites
+- [Docker](https://www.docker.com/get-started) or [Podman](https://podman.io/)
+- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
 
+### Setup
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/azure/autorest.powershell
+   cd autorest.powershell
+   ```
 
-## Cloning this repository
+2. Open in VS Code and reopen in container:
+   - Open the folder in VS Code
+   - When prompted, click "Reopen in Container" (or press `F1` and select "Dev Containers: Reopen in Container")
+   - Wait for the container to build and initialize (this may take a few minutes on first run)
 
-``` powershell
-# clone recursively
-git clone https://github.com/azure/autorest.powershell
+3. Once the container is ready, all tools are pre-installed and configured:
+   - Node.js 18.20.4
+   - Rush 5.112.2
+   - PowerShell 7.5+
+   - .NET SDK 2.1
 
-# one-time
-cd autorest.powershell
-npm install
-```
+4. Build the project:
+   ```bash
+   rush update
+   rush rebuild
+   ```
 
-## Using RushJS
+## Manual Setup (Without Dev Container)
 
-This repository is built as a 'monorepo' using [RushJS](https://rushjs.io/) - which manages multiple nodejs projects in a single repository.
+### Requirements
 
-``` powershell
-# install nodejs modules for all projects in the monorepo
-rush update
+Use of this project requires the following:
+
+- **[Node.js LTS](https://nodejs.org)** (18.20.4) - We recommend using [nvs](https://github.com/jasongin/nvs) or [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions
+- **[Rush](https://rushjs.io/)** (5.112.2) - `npm install -g @microsoft/[email protected]`
+- **[PowerShell](https://github.com/PowerShell/PowerShell)** (7.0+) - Cross-platform, install from [GitHub releases](https://github.com/PowerShell/PowerShell/releases)
+- **[.NET SDK](https://dotnet.microsoft.com/download)** (2.1+) - Required for building C# components
+- **Recommended**: [Visual Studio Code](https://code.visualstudio.com/)
+
+### Cloning this repository
+
+```bash
+# Clone the repository
+git clone https://github.com/azure/autorest.powershell
+cd autorest.powershell
 ```
 
-Rush is used to make sure that package versions are consistent between sub-projects
+## Using Rush
 
-``` powershell
-# ensure all projects are using the same versions
+This repository is built as a monorepo using [Rush](https://rushjs.io/), which manages multiple Node.js projects in a single repository.
+
+```bash
+# First time setup: sync package versions
 rush sync-versions
 
-# install modules 
+# Install dependencies for all projects
 rush update
 ```
 
-## Compiling
+If you update dependencies in `package.json` files, run `rush update` again to install the new packages.
+
+## Building
 
-Rush is used to build `autorest.powershell`
+Build all projects in the correct dependency order:
 
-``` powershell
-# build everything
+```bash
+# Clean build everything from scratch
 rush rebuild
+
+# Incremental build (faster, only rebuilds changed projects)
+rush build
 ```
 
-You can use `watch` to compile when a file is changed, which will rebuild dependencies automatically.
-Just kill the process with ctrl-c to stop it.
+### Watch Mode
 
-``` powershell
-# start watching 
+For active development, you can use watch mode to automatically rebuild when files change:
+
+```bash
+# Watch mode - rebuilds on file changes
 rush watch
 ```
 
-## Using your locally built version of `autorest.powershell`
+Press `Ctrl+C` to stop the watch process.
+
+## Using Your Local Build
 
-To use the locally built version of the plugin, add `--use:<path>` to the command line 
+To use your locally built version of the plugin, use the `--use` flag with AutoRest:
 
-``` powershell
-# using a local build
-> autorest --use:c:/work/autorest.powershell <...arguments>
+```bash
+# Using local build (cross-platform path)
+autorest --use:$PWD/powershell --powershell --input-file:path/to/spec.yaml --output-folder:./output
 
+# Or with absolute path
+autorest --use:/path/to/autorest.powershell/powershell --powershell <...other-arguments>
 ```
 
-### Debugging 
+**Note**: Use `$PWD` on Linux/macOS or `${PWD}` in PowerShell for the current directory. On Windows Command Prompt, use `%CD%`.
+
+## Debugging
+
+### Debugging AutoRest Generation
+
+1. Start AutoRest with the debugger flag (it will wait for the debugger to attach):
+   ```bash
+   autorest --use:$PWD/powershell --powershell.debugger --input-file:spec.yaml
+   ```
+
+2. In VS Code:
+   - Open the `autorest.powershell` folder
+   - Press `F5` to attach the debugger
+   - You'll see "Debugger attached." in the AutoRest console
+   - Set breakpoints and debug as needed
+
+### Debugging in VS Code
 
-1. Start generating: `autorest --use:C:\path\to\local\autorest.powershell --powershell.debugger`. It will wait for debugger to attach.
-1. Start debugging: open autorest.powershell repo in vscode; press `F5`. You will see "Debugger attached." in your autorest console, then you can start debugging.
+The repository includes VS Code launch configurations in `.vscode/launch.json` for debugging TypeScript code.
 
 ### Testing