Add documentation

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Test RemoteForce
+name: Test RemoteForge
 on:
   push:
     branches:

README.md

@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jborean93/RemoteForge/blob/main/LICENSE)
 
 PowerShell RemoteForge module used for managing and using custom PSRemoting transports.
+By itself this module only exposes the builtin transports `ssh` and `wsman`, it is designed to be used as a dependency of other modules to provide a simpler way of writing transports and a common interface for end users to use those transports.
 
 See [RemoteForge index](docs/en-US/RemoteForge.md) for more details.
 
@@ -15,10 +16,94 @@ These cmdlets have the following requirements
 
 * PowerShell v7.3 or newer
 
-## ExamplesPSEtw
-TODO
+## Builtin Forges
+
+The following forges are provided by this module:
+
+|Name|Description|ConnectionInfo Cmdlet|
+|-|-|-|
+|`ssh`|The builtin PowerShell SSH transport|[New-SSHForgeInfo](./docs/en-US/New-SSHForgeInfo.md)|
+|`wsman`|The builtin PowerShell WSMan/WinRM transport|[New-WSManForgeInfo](./docs/en-US/New-WSManForgeInfo.md)|
+
+The WSMan transport on Linux requires the WSMan C library to be setup properly which is outside the scope of this module.
+The ConnectionInfo Cmdlet specified can be used to create a [RunspaceConnectionInfo](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.runspaceconnectioninfo?view=powershellsdk-7.3.0) for that transport which can be used in the underlying PowerShell .NET API, provided to [Invoke-Remote](./docs/en-US/Invoke-Remote.md), [Enter-Remote](./docs/en-US/Enter-Remote.md), or [New-RemoteForgeSession](./docs/en-US/New-RemoteForgeSession.md).
+
+## Extra Forges
+
+These forges are not part of this module but can be installed separated and used with the [Invoke-Remote](./docs/en-US/Invoke-Remote.md), [Enter-Remote](./docs/en-US/Enter-Remote.md), and [New-RemoteForgeSession](./docs/en-US/New-RemoteForgeSession.md) cmdlets provided by this module.
+
+|Name|Description|ConnectionInfo Cmdlet|
+|-|-|-|
+
+See the documentation for each linked forge module for more information on how to use them.
+
+## Examples
+
+The following cmdlets can be used with a registered forge:
+
++ [Invoke-Remote](./docs/en-US/Invoke-Remote.md) - replacement for [Invoke-Command](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/invoke-command)
++ [Enter-Remote](./docs/en-US/Enter-Remote.md) - replacement for [Enter-PSSession](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/enter-pssession)
++ [New-RemoteForgeSession](./docs/en-US/New-RemoteForgeSession.md) - replacement for [New-PSSession](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/new-pssession)
+
+These three cmdlets accept a forge connection through the `-ConnectionInfo` parameter which describe the connection details.
+See [about_RemoteForgeConnectionInfo](./docs/en-US/about_RemoteForgeConnectionInfo.md) for more details on how this connection an be specified.
+
+The [Invoke-Remote](./docs/en-US/Invoke-Remote.md) cmdlet can be used to invoke a scriptblock or script file on the target host(s)
+
+```powershell
+# Connects over ssh to hostname
+Invoke-Remote -ConnectionInfo ssh:hostname {
+    Get-Item foo
+}
+
+# Connects over wsman to hostname
+Invoke-Remote -ConnectionInfo wsman:hostname {
+    Get-Item foo
+}
+
+# Connects to both hostname over ssh and a custom forge called
+# process (not included). This is done in parallel up to the
+# defined -ThrottleLimit
+Invoke-Remote ssh:hostname, process:foo {
+    Get-Item foo
+}
+```
+
+If the forge name is not used in the connection string, the default forge is used.
+The variable `$PSRemoteForgeDefault` can be used to specify the default forge in the current scope, if unset it defaults to `ssh`.
+
+```powershell
+# Will run host1, host2, host3 all over wsman in parallel.
+$PSRemoteForgeDefault = 'wsman'
+Invoke-Remote host1, host2, host3 {
+    Get-Item foo
+}
+```
+
+The [Enter-Remote](./docs/en-US/Enter-Remote.md) cmdlet can only be used in interactive scenarios.
+Just like `Enter-PSSession`, it provides an interactive PSHost over the connection specified.
+Type in `exit` to exit the remote PSHost and return back to the local host that entered the session.
+Do not use this cmdlet in a script as it will not work.
+
+The [New-RemoteForgeSession](./docs/en-US/New-RemoteForgeSession.md) cmdlet can be used to create a [PSSession](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.pssession?view=powershellsdk-7.4.0) object.
+This is useful for long lived session that run multiple commands with `Invoke-Remote` or when needing to interact with the builtin cmdlets `Invoke-Command`, `Enter-PSSession`, etc.
+
+```powershell
+# Creates the PSSession object
+$session = New-RemoteForgeSession ssh:foo
+
+# Runs two separate commands on the PSSession using the builtin
+# Invoke-Command cmdlet.
+Invoke-Command -Session $session { 'foo' }
+
+Invoke-Command -Session $session { 'bar' }
+
+# The session should be closed when no longer needed
+$session | Remove-PSSession
+```
 
 ## Installing
+
 The easiest way to install this module is through [PowerShellGet](https://docs.microsoft.com/en-us/powershell/gallery/overview).
 
 You can install this module by running either of the following `Install-PSResource` or `Install-Module` command.

docs/en-US/Enter-Remote.md

@@ -1,14 +1,14 @@
 ---
 external help file: RemoteForge.dll-Help.xml
 Module Name: RemoteForge
-online version:
+online version: https://www.github.com/jborean93/RemoteForge/blob/main/docs/en-US/Enter-Remote.md
 schema: 2.0.0
 ---
 
 # Enter-Remote
 
 ## SYNOPSIS
-{{ Fill in the Synopsis }}
+Starts an interactive session with a PSRemoting transport.
 
 ## SYNTAX
 
@@ -18,21 +18,34 @@ Enter-Remote [-ConnectionInfo] <StringForgeConnectionInfoPSSession>
 ```
 
 ## DESCRIPTION
-{{ Fill in the Description }}
+The `Enter-Remote` cmdlet starts an interactive session with a single remote transport.
+During the session, the commands typed into host are run on the transport target, just as if it was a local process.
+This cmdlet is designed to replicate the functionality of [Enter-PSSession](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/enter-pssession) but with support for forges.
+
+To end the interactive session and disconnect from the remote transport, use the `Exit-PSSession` cmdlet or type `exit`.
 
 ## EXAMPLES
 
-### Example 1
+### Example 1: Start an interactive session
+```powershell
+PS C:\> Enter-Remote ssh:hostname
+```
+
+Starts an interactive session over `ssh` to `hostname`.
+
+### Example 2: Start session using connection info object
 ```powershell
-PS C:\> {{ Add example code here }}
+PS C:\> $connInfo = New-SSHForgeInfo -HostName foo -UserName user
+PS C:\> Enter-Remote $connInfo
 ```
 
-{{ Add example description here }}
+Creates an `SSHConnectionInfo` object using [New-SSHForgeInfo](./New-SSHForgeInfo.md) and uses it as the transport target.
 
 ## PARAMETERS
 
 ### -ApplicationArguments
-{{ Fill ApplicationArguments Description }}
+A PrimitiveDictionary that is sent to the remote session.
+The value specified here can be accessed through the `$PSSenderInfo.ApplicationArguments` property value.
 
 ```yaml
 Type: PSPrimitiveDictionary
@@ -47,7 +60,17 @@ Accept wildcard characters: False
 ```
 
 ### -ConnectionInfo
-{{ Fill ConnectionInfo Description }}
+The `-ConnectionInfo` parameter accepts four different objects types:
+
++ `String` - forge connection string
+
++ `IRemoteForge` - forge connection object
+
++ `RunspaceConnectionInfo` - PowerShell connection info object
+
++ `PSSession` - an already created PSSession object
+
+See [about_RemoteForgeConnectionInfo](./about_RemoteForgeConnectionInfo.md) for more details.
 
 ```yaml
 Type: StringForgeConnectionInfoPSSession
@@ -62,7 +85,7 @@ Accept wildcard characters: False
 ```
 
 ### -ProgressAction
-{{ Fill ProgressAction Description }}
+New common parameter introduced in PowerShell 7.4.
 
 ```yaml
 Type: ActionPreference
@@ -82,9 +105,21 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
+This cmdlet does not accept any pipeline input.
+
 ## OUTPUTS
 
-### System.Object
+### None
+This cmdlet does not output any object.
+
 ## NOTES
+Do not attempt to run this cmdlet in a script, it can only be used interactively.
+See [Invoke-Remote](./Invoke-Remote.md) to run a scriptblock in a remote transport session instead.
+
+While the session is interactive it cannot be used to invoke external applications that require interaction through the console.
+For example running a command like `vim`, `sudo`, etc that require interaction through the console will not work.
+This is a fundamental limiation of PSRemoting and cannot be fixed.
 
 ## RELATED LINKS
+
+[Enter-PSSession](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/enter-pssession)

docs/en-US/Get-RemoteForge.md

@@ -8,7 +8,7 @@ schema: 2.0.0
 # Get-RemoteForge
 
 ## SYNOPSIS
-{{ Fill in the Synopsis }}
+Gets the registered forges.
 
 ## SYNTAX
 
@@ -17,21 +17,40 @@ Get-RemoteForge [[-Name] <String[]>] [-ProgressAction <ActionPreference>] [<Comm
 ```
 
 ## DESCRIPTION
-{{ Fill in the Description }}
+Gets the forges that have been registered in the current session.
+This includes details such as the forge name and description if provided during registration.
+
+Forges can be registered with [Register-RemoteForge](./Register-RemoteForge.md) and unregistered with [Unregister-RemoteForge](./Unregister-RemoteForge.md).
 
 ## EXAMPLES
 
-### Example 1
+### Example 1: Get all registered forges
+```powershell
+PS C:\> Get-RemoteForge
+```
+
+Gets all registered forges.
+
+### Example 2: Get specific forge
 ```powershell
-PS C:\> {{ Add example code here }}
+PS C:\> Get-RemoteForge -Name ssh
 ```
 
-{{ Add example description here }}
+Gets the details of the `ssh` forge.
+
+### Example 3: Get forge with wildcard
+```powershell
+PS C:\> Get-RemoteForge -Name ws*
+```
+
+Gets all forges that match the wildcard `ws*`.
 
 ## PARAMETERS
 
 ### -Name
-{{ Fill Name Description }}
+The name of the forge to filter by.
+This supports simple wildcard matching with `*`, `?`, `[`, and `]`.
+Omit this parameter to get all registered forges.
 
 ```yaml
 Type: String[]
@@ -46,7 +65,7 @@ Accept wildcard characters: False
 ```
 
 ### -ProgressAction
-{{ Fill ProgressAction Description }}
+New common parameter introduced in PowerShell 7.4.
 
 ```yaml
 Type: ActionPreference
@@ -66,9 +85,13 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
+This cmdlet does not accept any pipeline input.
+
 ## OUTPUTS
 
-### System.Object
+### RemoteForge.RemoteForgeRegistration
+This cmdlet outputs a `RemoteForgeRegistration` object for each registered forge. This object contains the `Name` property being the forge name and a `Description` of the forge.
+
 ## NOTES
 
 ## RELATED LINKS