Remove custom IProjectCapabilitiesProvider docs

It's too hard to do this correctly, and generally other approaches are better.

Author: drewnoakes

doc/overview/about_project_capabilities.md

@@ -6,9 +6,11 @@ file extension does not help if you want to check for WPF vs. WinForms
 vs. Windows 8 XAML, for example. There are a great many different aspects
 to a project that may be present regardless of language. Do you want code
 that runs against any Windows 8 targeting project regardless of language?
-Do you want to target just Javascript Win8 projects but not LightSwitch
+Do you want to target just JavaScript Win8 projects but not LightSwitch
 JS projects? Project capability checks are the answer.
 
+## Checking capabilities
+
 The presence of some capability can be detected on a given project with
 code such as:
 
@@ -26,17 +28,42 @@ method in order to test for combinations of capabilities (including
 AND, OR, NOT logic). Read more about [the supported syntax and
 operators](https://msdn.microsoft.com/library/microsoft.visualstudio.shell.interop.ivsbooleansymbolexpressionevaluator.evaluateexpression.aspx).
 
-## How to declare project capabilities in your project
+## Filtering MEF parts via capabilities
+
+Classes exported via MEF can declare the project capabilities under which they apply. See [MEF](mef.md) for more information.
+
+## Defining capabilities via MSBuild
 
 Project capabilities can be declared in several ways, the easiest of which
-being to add this MSBuild item to your .targets file:
+being to add this MSBuild item to your `.targets` file:
 
 ```xml
 <ItemGroup>
   <ProjectCapability Include="MyOwnCapability" />
 </ItemGroup>
 ```
 
+## Defining fixed capabilities for a project type
+
+Some capabilities are static/fixed for a given project type. These capabilities should be defined directly on the project type registration.
+
+For example:
+
+```csharp
+[assembly: ProjectTypeRegistration(
+    projectTypeGuid: MyProjectType.Guid,
+    displayName: "#1",
+    displayProjectFileExtensions: "#2",
+    defaultProjectExtension: "myproj",
+    language: "MyLang",
+    resourcePackageGuid: MyPackage.PackageGuid,
+    Capabilities = "MyProject; AnotherCapability")] // Define capabilities here
+```
+
+Capabilities defined via the `ProjectTypeRegistrationAttribute.Capabilities` property are available on all projects loaded for that project type. Multiple values are separated by semicolon (`;`).
+
+Sometimes you'll need capabilities to be defined very early in a project's lifecycle. These fixed capabilities are available from
+
 ## Viewing a project's capabilities
 
 To see the capabilities a CPS project defines, add the `DiagnoseCapabilities` project capability to turn on a tree in the VS Solution Explorer that lists all capabilities of the project:
@@ -96,7 +123,7 @@ It's very important that project capabilities you define fit this criteria:
   - Bad: `CS`
 - May include a version number, when necessary, but is usually discouraged.
 
-### Dynamic project capabilities
+## Dynamic project capabilities
 
 Capablities of a project can be changed without reloading the project.
 Read more about [dynamic project capabilities](dynamicCapabilities.md).

doc/overview/dynamicCapabilities.md

@@ -53,57 +53,6 @@ public MyComponent(ConfiguredProject configuredProject)
 The `DeployProviders` collection will contain a set of `IDeployProvider` filtered by the current capabilities
 of the configuredProject. The content of the collection can change over the time. 
 
-## Defining fixed capabilities for a project type
-
-Some capabilities are static/fixed for a given project type. These capabilities should be defined directly on the
-project type registration.
-
-For example:
-
-```c#
-[assembly: ProjectTypeRegistration(
-    projectTypeGuid: MyProjectType.Guid,
-    displayName: "#1",
-    displayProjectFileExtensions: "#2",
-    defaultProjectExtension: "myproj",
-    language: "MyLang",
-    resourcePackageGuid: MyPackage.PackageGuid,
-    Capabilities = "MyProject")]
-```
-
-Capabilities defined via the `ProjectTypeRegistrationAttribute.Capabilities` property are available on all projects loaded for that project type.
-
-## Dynamically producing project capabilities
-
-Capabilities can be added to a project at run-time via code. To do so, export an instance of
-`IProjectCapabilitiesProvider`. The easiest way to do this is to subclass `ProjectCapabilitiesProviderBase`
-and override the `GetCapabilitiesAsync` method.
-
-For example, if your project should only have a certain capability on Tuesday, you could use:
-
-```c#
-[Export(ExportContractNames.Scopes.UnconfiguredProject, typeof(IProjectCapabilitiesProvider))]
-[AppliesTo("MyProjectCapability")] // Replace with capabilities that define when your provider should be active
-internal class TuesdayProjectCapabilityProvider : ProjectCapabilitiesProviderBase
-{
-    [ImportingConstructor]
-    public TuesdayProjectCapabilityProvider(UnconfiguredProject project)
-        : base(nameof(TuesdayProjectCapabilityProvider), project.Services.ThreadingPolicy.JoinableTaskContext, project.Services.DataSourceRegistry, configuredProjectLevel: false)
-    {
-    }
-
-    protected override Task<ImmutableHashSet<string>> GetCapabilitiesAsync(CancellationToken cancellationToken)
-    {
-        // Replace this with whatever logic you require.
-        return DateTime.Now.DayOfWeek == DayOfWeek.Tuesday
-            ? Task.FromResult(Empty.CapabilitiesSet.Add("Tuesday"))
-            : Task.FromResult(Empty.CapabilitiesSet);
-    }
-}
-```
-
-Note there can be a chicken/egg problem here, where one capability enables a provider (via `AppliesTo`) that then adds another capability, and so on.
-
 ## How to prevent seeing capability changes in the middle of an execution
 
 When changes are made to the project, just like other dataflows inside CPS, capabilites are being recalculated