docs(nx-plugin): document local plugin functionality (#9564)

docs/shared/devkit-and-nx-plugins.md

@@ -42,6 +42,10 @@ executors.
 
 The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [custom generators](/generators/workspace-generators) and [executors](/executors/creating-custom-builders) for your own workspace. You can also write your own plugin and share it with the community. The [Nx Plugin](/nx-plugin/overview) plugin provides guidance on how you can build your own custom plugins.
 
+### Local workspace plugins
+
+Nx plugins can also be used in the workspace they are generated inside of. For example, if you generate a plugin with `nx g @nrwl/nx-plugin my-plugin --importPath @my-org/my-plugin`, you will be able to immediately make use of generators and executors within it. This would look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors. If you are only planning on making use of generators, Nx provides workspace generators which can be used rather than whole plugins. Generating a full plugin allows you to take advantage of all of the capabilities above, including project inference and graph extension, which is not possible when solely using workspace generators. Additionally, your local plugin could be set as the default collection in `nx.json`, such that running `nx g lib` would call your workspace plugin's lib generator.
+
 ### Listing Nx plugins
 
 Nx provides a list of installed and available plugins from Nrwl and community maintainers. Plugins maintained by Nrwl

docs/shared/nx-plugin.md

@@ -83,13 +83,13 @@ Full E2Es are supported (and recommended) and will run everything on the file sy
 
 ## Testing your plugin
 
-One of the biggest benefits that the Nx Plugin package provides is support for E2E testing.
+One of the biggest benefits that the Nx Plugin package provides is support for E2E and unit testing.
 
 When the E2E app runs, a temporary E2E directory is created in the root of the workspace. This directory is a blank Nx workspace, and will have the plugin's built package installed locally.
 
 ### E2E Testing file
 
-When the plugin is generated, a test file is created in the `my-plugin-e2e` app. Inside this test file, there are already tests for making sure that the executor ran, checking if directories are created with the `--directory` option, and checking if tags are added to `nx.json`.
+When the plugin is generated, a test file is created in the `my-plugin-e2e` app. Inside this test file, there are already tests for making sure that the executor ran, checking if directories are created with the `--directory` option, and checking if tags are added to the project configuration.
 
 We'll go over a few parts of a test file below:
 
@@ -145,9 +145,13 @@ To make sure that assets are copied to the dist folder, open the plugin's `proje
 }
 ```
 
+## Using your Nx Plugin
+
+To use your plugin, simply list it in `nx.json` or use its generators and executors as you would for any other plugin. This could look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors. It should be usable in all of the same ways as published plugins in your local workspace immediately after generating it. This includes setting it up as the default collection in `nx.json`, which would allow you to run `nx g lib` and hit your plugin's generator.
+
 ## Publishing your Nx Plugin
 
-To publish your plugin follow these steps:
+In order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:
 
 1. Build your plugin with the command `nx run my-plugin:build`
 1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.

docs/shared/tools-workspace-builders.md

@@ -1,3 +1,5 @@
+> In Nx 13.10+, local nx plugins can contain executors that are used in the workspace. When creating a custom executor for your workspace, look into the [nx-plugin guide](/nx-plugin/overview) to simplify the build process.
+
 # Creating Custom Executors
 
 Creating Executors for your workspace standardizes scripts that are run during your development/building/deploying tasks in order to enable Nx's `affected` command and caching capabilities.