IN PROGRESS: Adding API documentation

Author: daviwil

.gitignore

@@ -26,6 +26,10 @@ lock
 registered_data.ini
 .vs/
 
+docs/_site/
+docs/metadata/
+tools/
+
 # quickbuild.exe
 /VersionGeneratingLogs/
 QLogs

docs/contributing.md renamed to CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# API Reference
+
+## @Microsoft.PowerShell.EditorServices
+
+## @Microsoft.PowerShell.EditorServices.Session

docs/api/index.md

@@ -0,0 +1,71 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [ "*.csproj" ],
+          "cwd": "../src/PowerShellEditorServices",
+          "exclude": [ "**/obj/**", "**/bin/**" ]
+        }
+      ],
+      "dest": "metadata/api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "cwd": "metadata/api",
+        "files": [
+          "**/**.yml"
+        ],
+        "dest": "api"
+      },
+      {
+        "cwd": "../",
+        "files": [
+          "CONTRIBUTING.md",
+          "CHANGELOG.md"
+        ]
+      },
+      {
+        "cwd":  ".",
+        "files": [
+          "toc.yml",
+          "index.md",
+          "api/index.md",
+          "guide/**.md"
+        ],
+        "exclude": [
+          "metadata/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "apidoc/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "template": [
+      "default"
+    ]
+  }
+}

docs/docfx.json

@@ -0,0 +1,150 @@
+# Extending the Host Editor
+
+PowerShell Editor Services exposes a common extensibility model which allows
+you to write extension code in PowerShell that works across any editor that
+uses PowerShell Editor Services.
+
+## API Overview
+
+### Introducing `$psEditor`
+
+The entry point for the PowerShell Editor Services extensibility model is the `$psEditor`
+object of the type @Microsoft.PowerShell.EditorServices.Extensions.EditorObject. For
+those familiar with the PowerShell ISE's `$psISE` object, the `$psEditor` object is very
+similar.  The primary difference is that this model has been generalized to work against
+any editor which leverages PowerShell Editor Services for its PowerShell editing experience.
+
+> NOTE: For now the `$psEditor` object is limited as it has just been
+> introduced.  If you have ideas for other useful APIs it could expose
+> please file an issue on our GitHub page.
+
+This object gives access to all of the high-level services in the current
+editing session.  For example, the @Microsoft.PowerShell.EditorServices.Extensions.EditorObject.Workspace
+property gives access to the editor's workspace, allowing you to create or open files
+in the editor.
+
+### Usage Examples
+
+#### Opening a file in the editor
+
+**TODO**
+
+#### Manipulating the user's active file buffer
+
+**TODO**
+
+#### Setting the selection based on the cursor position
+
+**TODO**
+
+
+The `$psEditor` object gives you the ability to write a script that can automate the
+host editor when run inside of it.  However, you may not want to give a user a plan
+script to run to perform some operation.
+within the host editor, automate operations in the editor.  What if you'd like to
+
+## Registering Editor Commands
+
+It might be helpful to register a command with the editor so that your extension
+functionality is easily accessible to the user.  The `Register-EditorCommand`
+cmdlet can be used to register either a function, cmdlet, or ScriptBlock as a
+command in the host editor.
+
+### Registering a cmdlet or function command
+
+```powershell
+function Invoke-MyCommand {
+    Write-Output "My extension function was invoked!"
+}
+
+Register-EditorCommand `
+    -Name "MyExt.MyExtensionFunction" `
+    -DisplayName "My extension function" `
+    -Function MyExtensionFunction
+```
+
+### Registering a script block command
+
+```powershell
+Register-EditorCommand `
+    -Name "MyExt.MyExtensionScriptBlock" `
+    -DisplayName "My extension script block" `
+    -ScriptBlock { Write-Output "My extension script block was invoked!" }
+```
+
+### The @Microsoft.PowerShell.EditorServices.Extensions.EditorContext parameter
+
+Your function, cmdlet, or ScriptBlock can optionally accept a single parameter
+of type @Microsoft.PowerShell.EditorServices.Extensions.EditorContext which provides
+information about the state of the host editor at the time your command was
+invoked.  With this object you can easily perform operations like manipulatin the
+state of the user's active editor buffer or changing the current selection.
+
+The usual convention is that a `$context` parameter is added to your editor
+command's function.  For now it is recommended that you fully specify the
+type of the @Microsoft.PowerShell.EditorServices.Extensions.EditorContext object
+so that you get full IntelliSense on your context parameter.
+
+Here is an example of using the `$context` parameter:
+
+```powershell
+Register-EditorCommand `
+    -Name "MyExt.MyExtensionScriptBlockWithContext" `
+    -DisplayName "My extension script block with context" `
+    -ScriptBlock {
+        param([Microsoft.PowerShell.EditorServices.Extensions.EditorContext]$context)
+        Write-Output "The user's cursor is on line $($context.CursorPosition.Line)!"
+    }
+```
+
+### Suppressing command output
+
+If you would like for your editor command to run without its output being
+written to the user's console, you can use the `-SuppressOutput` switch
+parameter of the `Register-EditorCommand` cmdlet.  We recommend that you
+use this parameter if your command does not need to write output to the
+user's console.
+
+Regardless of whether the `-SuppressOutput` parameter is used, any errors
+that occur while running your editor command will be written to the user's
+console.
+
+## Using Editor Commands
+
+If you've registered an editor command, either through your own code or
+a module that you've installed, you can launch it using your editor's **Show
+additional commands from PowerShell modules** command.  Running this command
+will cause a list of commands to be displayed.  Here's an example of how this
+looks in Visual Studio Code:
+
+**TODO TODO TODO**
+
+> NOTE: In the future we hope to be able to register editor commands at the top level
+> so that these commands are easier to find and so that they also can be bound to
+> hotkeys for quick access.
+
+## Shipping an Extension Module
+
+You can easily ship a module containing editor commands which get registered
+if the module is loaded into an editor session.  Assuming that you've exported
+a function or cmdlet named `Invoke-MyExtensionCommand` in your module's psd1
+file, you can add this code at the very end of your module's psm1 file:
+
+```powershell
+if ($psEditor) {
+    Register-EditorCommand `
+        -Name "MyModule.MyExtensionCommand" `
+        -DisplayName "My extension command" `
+        -Function Invoke-MyExtensionCommand `
+        -SuppressOutput
+}
+```
+
+The user will now be able to import your module in their host editor's profile and
+your editor command will be immediately available after the PowerShell extension
+in that editor starts up.
+
+> NOTE: In the future we plan to provide an easy way for the user to opt-in
+> to the automatic loading of any editor command modules that they've installed
+> from the PowerShell Gallery.  If this interests you, please let us know on
+> [this GitHub issue](https://github.com/PowerShell/PowerShellEditorServices/issues/215).

docs/extensions.md

@@ -0,0 +1,3 @@
+# Introduction
+
+> NOTE: This section is currently under development.

docs/guide/extensions.md

@@ -0,0 +1,4 @@
+# [Introduction](introduction.md)
+# [Using the .NET API](using_the_dotnet_api.md)
+# [Using the Host Process](using_the_host_process.md)
+# [Extending the Host Editor](extensions.md)