Allow additional files to be copied as part of template extraction

Author: jskeet

standard/documentation-comments.md

@@ -711,7 +711,7 @@ IDs:
 
 **Fields** are represented by their fully qualified name.
 
-<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsFields"} -->
+<!-- Example: {template:"standalone-lib", name:"IDStringsFields", additionalFiles:["Acme.cs"], ignoredWarnings:["CS0169","CS0649"]} -->
 ```csharp
 namespace Acme
 {
@@ -756,7 +756,7 @@ IDs:
 
 **Constructors**
 
-<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsConstructors", replaceEllipsis:true} -->
+<!-- Example: {template:"standalone-lib", name:"IDStringsConstructors", replaceEllipsis:true, additionalFiles:["Acme.cs"]} -->
 ```csharp
 namespace Acme
 {
@@ -779,7 +779,7 @@ IDs:
 
 **Finalizers**
 
-<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsFinalizers", replaceEllipsis: true} -->
+<!-- Example: {template:"standalone-lib", name:"IDStringsFinalizers", replaceEllipsis: true, additionalFiles:["Acme.cs"]} -->
 ```csharp
 namespace Acme
 {
@@ -798,7 +798,7 @@ IDs:
 
 **Methods**
 
-<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsMethods", replaceEllipsis:true} -->
+<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsMethods", replaceEllipsis:true, additionalFiles:["Acme.cs"], ignoredWarnings:["CS0169","CS0649"]} -->
 ```csharp
 namespace Acme
 {
@@ -878,7 +878,7 @@ IDs:
 
 **Events**
 
-<!-- IncompleteExample: {template:"standalone-lib", name:"IDStringsEvents"} -->
+<!-- Example: {template:"standalone-lib", name:"IDStringsEvents", additionalFiles:["Acme.cs"], ignoredWarnings:["CS0067"]} -->
 ```csharp
 namespace Acme
 {

tools/ExampleExtractor/ExampleMetadata.cs

@@ -28,6 +28,11 @@ public class ExampleMetadata
     public bool InferOutput { get; set; }
     public string ExpectedException { get; set; }
 
+    /// <summary>
+    /// Additional files to copy from the special "additional-files" template directory.
+    /// </summary>
+    public List<string> AdditionalFiles { get; set; }
+
     // Information provided by the example extractor
     public string MarkdownFile { get; set; }
     public int StartLine { get; set; }

tools/ExampleExtractor/Program.cs

@@ -68,7 +68,7 @@
             anyErrors = true;
             continue;
         }
-        template.Apply(example, outputDirectory);
+        template.Apply(example, outputDirectory, templateDirectory);
     }
 }
 Console.WriteLine("Finished example extraction.");

tools/ExampleExtractor/Template.cs

@@ -4,6 +4,7 @@ namespace ExampleExtractor;
 
 internal class Template
 {
+    private const string AdditionalFilesDirectory = "additional-files";
     private const string ExampleCodeSubstitution = "$example-code";
     private const string ExampleNameSubstitution = "$example-name";
 
@@ -21,7 +22,8 @@ private Template(string name, Dictionary<string, string> files)
     /// </summary>
     /// <param name="example">The example to apply.</param>
     /// <param name="rootOutputDirectory">The root output directory. (A subdirectory for the example will be created within this.)</param>
-    internal void Apply(Example example, string rootOutputDirectory)
+    /// <param name="rootTemplateDirectory">The root template directory, used for finding additional files if necessary.</param>
+    internal void Apply(Example example, string rootOutputDirectory, string rootTemplateDirectory)
     {
         var outputDirectory = Path.Combine(rootOutputDirectory, example.Name);
         Directory.CreateDirectory(outputDirectory);
@@ -33,6 +35,15 @@ internal void Apply(Example example, string rootOutputDirectory)
                 .Replace(ExampleNameSubstitution, example.Name);
             File.WriteAllText(file, code);
         }
+        if (example.Metadata.AdditionalFiles is List<string> additionalFiles)
+        {
+            foreach (var additionalFile in additionalFiles)
+            {
+                string sourceFile = Path.Combine(rootTemplateDirectory, AdditionalFilesDirectory, additionalFile);
+                string destFile = Path.Combine(outputDirectory, additionalFile);
+                File.Copy(sourceFile, destFile);
+            }
+        }
         var metadataJson = JsonConvert.SerializeObject(example.Metadata);
         File.WriteAllText(Path.Combine(outputDirectory, ExampleMetadata.MetadataFile), metadataJson);
     }
@@ -46,6 +57,7 @@ private static Template LoadTemplate(string directory)
     {
         var name = Path.GetFileName(directory);
         var files = Directory.GetFiles(directory)
+            .Where(file => Path.GetFileName(file) != AdditionalFilesDirectory)
             .ToDictionary(file => Path.GetFileName(file), file => File.ReadAllText(file));
         return new Template(name, files);
     }

tools/example-templates/additional-files/Acme.cs

@@ -0,0 +1,7 @@
+// Common types used in documentation-comments.md
+namespace Acme
+{
+    enum Color { Red, Blue, Green }
+    public interface IProcess {}
+    public delegate void Del();
+}

tools/example-templates/additional-files/README.md

@@ -0,0 +1,4 @@
+This directory is not a template in itself, but contains additional
+files that can be copied into any example. This avoids having to
+create separate templates for each file which is common across
+multiple templates.