/// <summary>
/// Generate HTML documentation for all the tasks
/// </summary>
/// <param name="NameToTask">Map of task name to implementation</param>
/// <param name="OutputFile">Output file</param>
static void GenerateDocumentation(Dictionary <string, ScriptTask> NameToTask, FileReference OutputFile)
{
// Find all the assemblies containing tasks
Assembly[] TaskAssemblies = NameToTask.Values.Select(x => x.ParametersClass.Assembly).Distinct().ToArray();
// Read documentation for each of them
Dictionary <string, XmlElement> MemberNameToElement = new Dictionary <string, XmlElement>();
foreach (Assembly TaskAssembly in TaskAssemblies)
{
string XmlFileName = Path.ChangeExtension(TaskAssembly.Location, ".xml");
if (File.Exists(XmlFileName))
{
// Read the document
XmlDocument Document = new XmlDocument();
Document.Load(XmlFileName);
// Parse all the members, and add them to the map
foreach (XmlElement Element in Document.SelectNodes("/doc/members/member"))
{
string Name = Element.GetAttribute("name");
MemberNameToElement.Add(Name, Element);
}
}
}
// Create the output directory
if (FileReference.Exists(OutputFile))
{
FileReference.MakeWriteable(OutputFile);
}
else
{
DirectoryReference.CreateDirectory(OutputFile.Directory);
}
// Write the output file
LogInformation("Writing {0}...", OutputFile);
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("<html>");
Writer.WriteLine(" <head>");
Writer.WriteLine(" <style>");
Writer.WriteLine(" table { border-collapse: collapse }");
Writer.WriteLine(" table, th, td { border: 1px solid black; }");
Writer.WriteLine(" </style>");
Writer.WriteLine(" </head>");
Writer.WriteLine(" <body>");
Writer.WriteLine(" <h1>BuildGraph Tasks</h1>");
foreach (string TaskName in NameToTask.Keys.OrderBy(x => x))
{
// Get the task object
ScriptTask Task = NameToTask[TaskName];
// Get the documentation for this task
XmlElement TaskElement;
if (MemberNameToElement.TryGetValue("T:" + Task.TaskClass.FullName, out TaskElement))
{
// Write the task heading
Writer.WriteLine(" <h2>{0}</h2>", TaskName);
Writer.WriteLine(" <p>{0}</p>", TaskElement.SelectSingleNode("summary").InnerXml.Trim());
// Start the parameter table
Writer.WriteLine(" <table>");
Writer.WriteLine(" <tr>");
Writer.WriteLine(" <th>Attribute</th>");
Writer.WriteLine(" <th>Type</th>");
Writer.WriteLine(" <th>Usage</th>");
Writer.WriteLine(" <th>Description</th>");
Writer.WriteLine(" </tr>");
// Document the parameters
foreach (string ParameterName in Task.NameToParameter.Keys)
{
// Get the parameter data
ScriptTaskParameter Parameter = Task.NameToParameter[ParameterName];
// Get the documentation for this parameter
XmlElement ParameterElement;
if (MemberNameToElement.TryGetValue("F:" + Parameter.FieldInfo.DeclaringType.FullName + "." + Parameter.Name, out ParameterElement))
{
string TypeName = Parameter.FieldInfo.FieldType.Name;
if (Parameter.ValidationType != TaskParameterValidationType.Default)
{
StringBuilder NewTypeName = new StringBuilder(Parameter.ValidationType.ToString());
for (int Idx = 1; Idx < NewTypeName.Length; Idx++)
{
if (Char.IsLower(NewTypeName[Idx - 1]) && Char.IsUpper(NewTypeName[Idx]))
{
NewTypeName.Insert(Idx, ' ');
}
}
TypeName = NewTypeName.ToString();
}
Writer.WriteLine(" <tr>");
Writer.WriteLine(" <td>{0}</td>", ParameterName);
Writer.WriteLine(" <td>{0}</td>", TypeName);
Writer.WriteLine(" <td>{0}</td>", Parameter.bOptional? "Optional" : "Required");
Writer.WriteLine(" <td>{0}</td>", ParameterElement.SelectSingleNode("summary").InnerXml.Trim());
Writer.WriteLine(" </tr>");
}
}
// Always include the "If" attribute
Writer.WriteLine(" <tr>");
Writer.WriteLine(" <td>If</td>");
Writer.WriteLine(" <td>Condition</td>");
Writer.WriteLine(" <td>Optional</td>");
Writer.WriteLine(" <td>Whether to execute this task. It is ignored if this condition evaluates to false.</td>");
Writer.WriteLine(" </tr>");
// Close the table
Writer.WriteLine(" <table>");
}
}
Writer.WriteLine(" </body>");
Writer.WriteLine("</html>");
}
}
/// <summary>
/// Gets information about the task with the given name
/// </summary>
/// <param name="TaskName">Name of the task</param>
/// <param name="Task">Receives task info for the named task</param>
/// <returns>True if the task name was found and Task is set, false otherwise.</returns>
public bool TryGetTask(string TaskName, out ScriptTask Task)
{
return(NameToTask.TryGetValue(TaskName, out Task));
}
/// <summary>
/// Generate HTML documentation for all the tasks
/// </summary>
/// <param name="NameToTask">Map of task name to implementation</param>
/// <param name="OutputFile">Output file</param>
static void GenerateDocumentation(Dictionary <string, ScriptTask> NameToTask, FileReference OutputFile)
{
// Find all the assemblies containing tasks
Assembly[] TaskAssemblies = NameToTask.Values.Select(x => x.ParametersClass.Assembly).Distinct().ToArray();
// Read documentation for each of them
Dictionary <string, XmlElement> MemberNameToElement = new Dictionary <string, XmlElement>();
foreach (Assembly TaskAssembly in TaskAssemblies)
{
string XmlFileName = Path.ChangeExtension(TaskAssembly.Location, ".xml");
if (File.Exists(XmlFileName))
{
// Read the document
XmlDocument Document = new XmlDocument();
Document.Load(XmlFileName);
// Parse all the members, and add them to the map
foreach (XmlElement Element in Document.SelectNodes("/doc/members/member"))
{
string Name = Element.GetAttribute("name");
MemberNameToElement.Add(Name, Element);
}
}
}
// Create the output directory
DirectoryReference.CreateDirectory(OutputFile.Directory);
FileReference.MakeWriteable(OutputFile);
Log("Writing {0}...", OutputFile);
// Parse the engine version
BuildVersion Version;
if (!BuildVersion.TryRead(BuildVersion.GetDefaultFileName(), out Version))
{
throw new AutomationException("Couldn't read Build.version");
}
// Write the output file
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("Availability: NoPublish");
Writer.WriteLine("Title: BuildGraph Predefined Tasks");
Writer.WriteLine("Crumbs: %ROOT%, Programming, Programming/Development, Programming/Development/BuildGraph, Programming/Development/BuildGraph/BuildGraphScriptTasks");
Writer.WriteLine("Description: This is a procedurally generated markdown page.");
Writer.WriteLine("version: {0}.{1}", Version.MajorVersion, Version.MinorVersion);
Writer.WriteLine("parent:Programming/Development/BuildGraph/BuildGraphScriptTasks");
Writer.WriteLine();
foreach (string TaskName in NameToTask.Keys.OrderBy(x => x))
{
// Get the task object
ScriptTask Task = NameToTask[TaskName];
// Get the documentation for this task
XmlElement TaskElement;
if (MemberNameToElement.TryGetValue("T:" + Task.TaskClass.FullName, out TaskElement))
{
// Write the task heading
Writer.WriteLine("### {0}", TaskName);
Writer.WriteLine();
Writer.WriteLine(ConvertToMarkdown(TaskElement.SelectSingleNode("summary")));
Writer.WriteLine();
// Document the parameters
List <string[]> Rows = new List <string[]>();
foreach (string ParameterName in Task.NameToParameter.Keys)
{
// Get the parameter data
ScriptTaskParameter Parameter = Task.NameToParameter[ParameterName];
// Get the documentation for this parameter
XmlElement ParameterElement;
if (MemberNameToElement.TryGetValue("F:" + Parameter.FieldInfo.DeclaringType.FullName + "." + Parameter.Name, out ParameterElement))
{
string TypeName = Parameter.FieldInfo.FieldType.Name;
if (Parameter.ValidationType != TaskParameterValidationType.Default)
{
StringBuilder NewTypeName = new StringBuilder(Parameter.ValidationType.ToString());
for (int Idx = 1; Idx < NewTypeName.Length; Idx++)
{
if (Char.IsLower(NewTypeName[Idx - 1]) && Char.IsUpper(NewTypeName[Idx]))
{
NewTypeName.Insert(Idx, ' ');
}
}
TypeName = NewTypeName.ToString();
}
string[] Columns = new string[4];
Columns[0] = ParameterName;
Columns[1] = TypeName;
Columns[2] = Parameter.bOptional? "Optional" : "Required";
Columns[3] = ConvertToMarkdown(ParameterElement.SelectSingleNode("summary"));
Rows.Add(Columns);
}
}
// Always include the "If" attribute
string[] IfColumns = new string[4];
IfColumns[0] = "If";
IfColumns[1] = "Condition";
IfColumns[2] = "Optional";
IfColumns[3] = "Whether to execute this task. It is ignored if this condition evaluates to false.";
Rows.Add(IfColumns);
// Get the width of each column
int[] Widths = new int[4];
for (int Idx = 0; Idx < 4; Idx++)
{
Widths[Idx] = Rows.Max(x => x[Idx].Length);
}
// Format the markdown table
string Format = String.Format("| {{0,-{0}}} | {{1,-{1}}} | {{2,-{2}}} | {{3,-{3}}} |", Widths[0], Widths[1], Widths[2], Widths[3]);
Writer.WriteLine(Format, "", "", "", "");
Writer.WriteLine(Format, new string('-', Widths[0]), new string('-', Widths[1]), new string('-', Widths[2]), new string('-', Widths[3]));
for (int Idx = 0; Idx < Rows.Count; Idx++)
{
Writer.WriteLine(Format, Rows[Idx][0], Rows[Idx][1], Rows[Idx][2], Rows[Idx][3]);
}
// Blank line before next task
Writer.WriteLine();
}
}
}
}
/// <summary>
/// Gets information about the task with the given name
/// </summary>
/// <param name="TaskName">Name of the task</param>
/// <param name="Task">Receives task info for the named task</param>
/// <returns>True if the task name was found and Task is set, false otherwise.</returns>
public bool TryGetTask(string TaskName, out ScriptTask Task)
{
return NameToTask.TryGetValue(TaskName, out Task);
}
