/// <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); }