/// <summary>
/// Generates documentation files for the available settings, by merging the XML documentation from the compiler.
/// </summary>
/// <param name="OutputFile">The documentation file to write</param>
public static void WriteDocumentation(FileReference OutputFile)
{
// Find all the configurable types
List <Type> ConfigTypes = FindConfigurableTypes();
// Find all the configurable fields from the given types
Dictionary <string, Dictionary <string, FieldInfo> > CategoryToFields = new Dictionary <string, Dictionary <string, FieldInfo> >();
FindConfigurableFields(ConfigTypes, CategoryToFields);
CategoryToFields = CategoryToFields.Where(x => x.Value.Count > 0).ToDictionary(x => x.Key, x => x.Value);
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Make sure we can write to the output file
if (FileReference.Exists(OutputFile))
{
FileReference.MakeWriteable(OutputFile);
}
else
{
DirectoryReference.CreateDirectory(OutputFile.Directory);
}
// Generate the documentation file
if (OutputFile.HasExtension(".udn"))
{
WriteDocumentationUDN(OutputFile, InputDocumentation, CategoryToFields);
}
else if (OutputFile.HasExtension(".html"))
{
WriteDocumentationHTML(OutputFile, InputDocumentation, CategoryToFields);
}
else
{
throw new BuildException("Unable to detect format from extension of output file ({0})", OutputFile);
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
/// <summary>
/// Generates documentation files for the available settings, by merging the XML documentation from the compiler.
/// </summary>
/// <param name="OutputFile">The documentation file to write</param>
public static void WriteDocumentation(FileReference OutputFile)
{
// Find all the configurable types
List <Type> ConfigTypes = FindConfigurableTypes();
// Find all the configurable fields from the given types
Dictionary <string, Dictionary <string, FieldInfo> > CategoryToFields = new Dictionary <string, Dictionary <string, FieldInfo> >();
FindConfigurableFields(ConfigTypes, CategoryToFields);
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Make sure we can write to the output file
if (FileReference.Exists(OutputFile))
{
FileReference.MakeWriteable(OutputFile);
}
else
{
DirectoryReference.CreateDirectory(OutputFile.Directory);
}
// Generate the documentation file
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("<html>");
Writer.WriteLine(" <body>");
Writer.WriteLine(" <h2>BuildConfiguration Properties</h2>");
foreach (KeyValuePair <string, Dictionary <string, FieldInfo> > CategoryPair in CategoryToFields)
{
string CategoryName = CategoryPair.Key;
Writer.WriteLine(" <h3>{0}</h3>", CategoryName);
Writer.WriteLine(" <dl>");
Dictionary <string, FieldInfo> Fields = CategoryPair.Value;
foreach (KeyValuePair <string, FieldInfo> FieldPair in Fields)
{
string FieldName = FieldPair.Key;
FieldInfo Field = FieldPair.Value;
XmlNode Node = InputDocumentation.SelectSingleNode(String.Format("//member[@name='F:{0}.{1}']/summary", Field.DeclaringType.FullName, Field.Name));
if (Node != null)
{
// Reflow the comments into paragraphs, assuming that each paragraph will be separated by a blank line
List <string> Lines = new List <string>(Node.InnerText.Trim().Split('\n').Select(x => x.Trim()));
for (int Idx = Lines.Count - 1; Idx > 0; Idx--)
{
if (Lines[Idx - 1].Length > 0 && !Lines[Idx].StartsWith("*") && !Lines[Idx].StartsWith("-"))
{
Lines[Idx - 1] += " " + Lines[Idx];
Lines.RemoveAt(Idx);
}
}
// Write the result to the .udn file
if (Lines.Count > 0)
{
Writer.WriteLine(" <dt>{0}</dt>", FieldName);
if (Lines.Count == 1)
{
Writer.WriteLine(" <dd>{0}</dd>", Lines[0]);
}
else
{
Writer.WriteLine(" <dd>");
for (int Idx = 0; Idx < Lines.Count; Idx++)
{
if (Lines[Idx].StartsWith("*") || Lines[Idx].StartsWith("-"))
{
Writer.WriteLine(" <ul>");
for (; Idx < Lines.Count && (Lines[Idx].StartsWith("*") || Lines[Idx].StartsWith("-")); Idx++)
{
Writer.WriteLine(" <li>{0}</li>", Lines[Idx].Substring(1).TrimStart());
}
Writer.WriteLine(" </ul>");
}
else
{
Writer.WriteLine(" {0}", Lines[Idx]);
}
}
Writer.WriteLine(" </dd>");
}
}
}
}
Writer.WriteLine(" </dl>");
}
Writer.WriteLine(" </body>");
Writer.WriteLine("</html>");
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
public static void WriteDocumentation(Type RulesType, FileReference OutputFile)
{
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Get the current engine version for versioning the page
BuildVersion Version;
if (!BuildVersion.TryRead(BuildVersion.GetDefaultFileName(), out Version))
{
throw new BuildException("Unable to read the current build version");
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Filter the properties into read-only and read/write lists
List <FieldInfo> ReadOnlyFields = new List <FieldInfo>();
List <FieldInfo> ReadWriteFields = new List <FieldInfo>();
foreach (FieldInfo Field in RulesType.GetFields(BindingFlags.Instance | BindingFlags.SetProperty | BindingFlags.Public))
{
if (!Field.FieldType.IsClass || !Field.FieldType.Name.EndsWith("TargetRules"))
{
if (Field.IsInitOnly)
{
ReadOnlyFields.Add(Field);
}
else
{
ReadWriteFields.Add(Field);
}
}
}
// Make sure the output file is writable
FileReference.MakeWriteable(OutputFile);
// Generate the UDN documentation file
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("Availability: NoPublish");
Writer.WriteLine("Title: Build Configuration Properties Page");
Writer.WriteLine("Crumbs:");
Writer.WriteLine("Description: This is a procedurally generated markdown page.");
Writer.WriteLine("Version: {0}.{1}", Version.MajorVersion, Version.MinorVersion);
Writer.WriteLine("");
if (ReadOnlyFields.Count > 0)
{
Writer.WriteLine("### Read-Only Properties");
Writer.WriteLine();
foreach (FieldInfo Field in ReadOnlyFields)
{
OutputField(InputDocumentation, Field, Writer);
}
Writer.WriteLine();
}
if (ReadWriteFields.Count > 0)
{
Writer.WriteLine("### Read/Write Properties");
foreach (FieldInfo Field in ReadWriteFields)
{
OutputField(InputDocumentation, Field, Writer);
}
Writer.WriteLine("");
}
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
public static void WriteDocumentation(Type RulesType, FileReference OutputFile)
{
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Filter the properties into read-only and read/write lists
List <FieldInfo> ReadOnlyFields = new List <FieldInfo>();
List <FieldInfo> ReadWriteFields = new List <FieldInfo>();
foreach (FieldInfo Field in RulesType.GetFields(BindingFlags.Instance | BindingFlags.SetProperty | BindingFlags.Public))
{
if (!Field.FieldType.IsClass || !Field.FieldType.Name.EndsWith("TargetRules"))
{
if (Field.IsInitOnly)
{
ReadOnlyFields.Add(Field);
}
else
{
ReadWriteFields.Add(Field);
}
}
}
// Make sure the output file is writable
if (FileReference.Exists(OutputFile))
{
FileReference.MakeWriteable(OutputFile);
}
else
{
DirectoryReference.CreateDirectory(OutputFile.Directory);
}
// Generate the documentation file
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("<html>");
Writer.WriteLine(" <body>");
if (ReadOnlyFields.Count > 0)
{
Writer.WriteLine(" <h2>Read-Only Properties</h2>");
Writer.WriteLine(" <dl>");
foreach (FieldInfo Field in ReadOnlyFields)
{
OutputField(InputDocumentation, Field, Writer);
}
Writer.WriteLine(" </dl>");
}
if (ReadWriteFields.Count > 0)
{
Writer.WriteLine(" <h2>Read/Write Properties</h2>");
Writer.WriteLine(" <dl>");
foreach (FieldInfo Field in ReadWriteFields)
{
OutputField(InputDocumentation, Field, Writer);
}
Writer.WriteLine(" </dl>");
}
Writer.WriteLine(" </body>");
Writer.WriteLine("</html>");
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
/// <summary>
/// Generates documentation files for the available settings, by merging the XML documentation from the compiler.
/// </summary>
/// <param name="OutputFile">The documentation file to write</param>
public static void WriteDocumentation(FileReference OutputFile)
{
// Find all the configurable types
List <Type> ConfigTypes = FindConfigurableTypes();
// Find all the configurable fields from the given types
Dictionary <string, Dictionary <string, FieldInfo> > CategoryToFields = new Dictionary <string, Dictionary <string, FieldInfo> >();
FindConfigurableFields(ConfigTypes, CategoryToFields);
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Get the current engine version for versioning the page
BuildVersion Version;
if (!BuildVersion.TryRead(BuildVersion.GetDefaultFileName(), out Version))
{
throw new BuildException("Unable to read the current build version");
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Make sure we can write to the output file
FileReference.MakeWriteable(OutputFile);
// Generate the UDN documentation file
using (StreamWriter Writer = new StreamWriter(OutputFile.FullName))
{
Writer.WriteLine("Availability: NoPublish");
Writer.WriteLine("Title: Build Configuration Properties Page");
Writer.WriteLine("Crumbs:");
Writer.WriteLine("Description: This is a procedurally generated markdown page.");
Writer.WriteLine("Version: {0}.{1}", Version.MajorVersion, Version.MinorVersion);
Writer.WriteLine("");
foreach (KeyValuePair <string, Dictionary <string, FieldInfo> > CategoryPair in CategoryToFields)
{
string CategoryName = CategoryPair.Key;
Writer.WriteLine("### {0}", CategoryName);
Writer.WriteLine();
Dictionary <string, FieldInfo> Fields = CategoryPair.Value;
foreach (KeyValuePair <string, FieldInfo> FieldPair in Fields)
{
string FieldName = FieldPair.Key;
FieldInfo Field = FieldPair.Value;
XmlNode Node = InputDocumentation.SelectSingleNode(String.Format("//member[@name='F:{0}.{1}']/summary", Field.DeclaringType.FullName, Field.Name));
if (Node != null)
{
// Reflow the comments into paragraphs, assuming that each paragraph will be separated by a blank line
List <string> Lines = new List <string>(Node.InnerText.Trim().Split('\n').Select(x => x.Trim()));
for (int Idx = Lines.Count - 1; Idx > 0; Idx--)
{
if (Lines[Idx - 1].Length > 0 && !Lines[Idx].StartsWith("*") && !Lines[Idx].StartsWith("-"))
{
Lines[Idx - 1] += " " + Lines[Idx];
Lines.RemoveAt(Idx);
}
}
// Write the result to the .udn file
if (Lines.Count > 0)
{
Writer.WriteLine("$ {0} : {1}", FieldName, Lines[0]);
for (int Idx = 1; Idx < Lines.Count; Idx++)
{
if (Lines[Idx].StartsWith("*") || Lines[Idx].StartsWith("-"))
{
Writer.WriteLine(" * {0}", Lines[Idx].Substring(1).TrimStart());
}
else
{
Writer.WriteLine(" * {0}", Lines[Idx]);
}
}
Writer.WriteLine();
}
}
}
}
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
public static void WriteDocumentation(Type RulesType, FileReference OutputFile)
{
// Get the path to the XML documentation
FileReference InputDocumentationFile = new FileReference(Assembly.GetExecutingAssembly().Location).ChangeExtension(".xml");
if (!FileReference.Exists(InputDocumentationFile))
{
throw new BuildException("Generated assembly documentation not found at {0}.", InputDocumentationFile);
}
// Read the documentation
XmlDocument InputDocumentation = new XmlDocument();
InputDocumentation.Load(InputDocumentationFile.FullName);
// Filter the properties into read-only and read/write lists
List <FieldInfo> ReadOnlyFields = new List <FieldInfo>();
List <FieldInfo> ReadWriteFields = new List <FieldInfo>();
foreach (FieldInfo Field in RulesType.GetFields(BindingFlags.Instance | BindingFlags.SetProperty | BindingFlags.Public))
{
if (!Field.FieldType.IsClass || !Field.FieldType.Name.EndsWith("TargetRules"))
{
if (Field.IsInitOnly)
{
ReadOnlyFields.Add(Field);
}
else
{
ReadWriteFields.Add(Field);
}
}
}
// Make sure the output file is writable
if (FileReference.Exists(OutputFile))
{
FileReference.MakeWriteable(OutputFile);
}
else
{
DirectoryReference.CreateDirectory(OutputFile.Directory);
}
// Generate the documentation file
if (OutputFile.HasExtension(".udn"))
{
WriteDocumentationUDN(OutputFile, ReadOnlyFields, ReadWriteFields, InputDocumentation);
}
else if (OutputFile.HasExtension(".html"))
{
WriteDocumentationHTML(OutputFile, ReadOnlyFields, ReadWriteFields, InputDocumentation);
}
else
{
throw new BuildException("Unable to detect format from extension of output file ({0})", OutputFile);
}
// Success!
Log.TraceInformation("Written documentation to {0}.", OutputFile);
}
