/// <summary>
/// Initializes a new instance of the <see cref="BuildStyle"/> class with the
/// specified style name, style type and style directory.
/// </summary>
/// <param name="name">
/// A <see cref="System.String"/> containing the name of this style.
/// </param>
/// <param name="directory">
/// A <see cref="System.String"/> containing the directory of the style.
/// <para>
/// This is only used for specifying the directory of custom or user-defined
/// style. If not specified or the specified directory is invalid, the
/// default Sandcastle style directory is used.
/// </para>
/// </param>
/// <param name="type">
/// An enumeration of the type <see cref="BuildStyleType"/> specifying the type
/// of the presentation style.
/// </param>
public BuildStyle(string name, string directory,
BuildStyleType type) : this(type)
{
_styleName = name;
if (!String.IsNullOrEmpty(directory))
{
_styleDir = new BuildDirectoryPath(directory);
}
}
public static string StyleFolder(BuildStyleType styleType)
{
if (styleType == BuildStyleType.ClassicWhite ||
styleType == BuildStyleType.ClassicBlue)
{
return("Vs2005");
}
return("Vs2005");
}
private void ReadXmlGeneral(XmlReader reader)
{
string startElement = reader.Name;
Debug.Assert(String.Equals(startElement, "propertyGroup"));
Debug.Assert(String.Equals(reader.GetAttribute("name"), "General"));
if (reader.IsEmptyElement)
{
return;
}
while (reader.Read())
{
if (reader.NodeType == XmlNodeType.Element)
{
if (String.Equals(reader.Name, "property",
StringComparison.OrdinalIgnoreCase))
{
string tempText = null;
switch (reader.GetAttribute("name").ToLower())
{
case "stylename":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_styleName = tempText;
}
break;
case "styletype":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_styleType = (BuildStyleType)Enum.Parse(
typeof(BuildStyleType), tempText, true);
}
break;
default:
// Should normally not reach here...
throw new NotImplementedException(reader.GetAttribute("name"));
}
}
}
else if (reader.NodeType == XmlNodeType.EndElement)
{
if (String.Equals(reader.Name, startElement, StringComparison.OrdinalIgnoreCase))
{
break;
}
}
}
}
/// <summary>
/// Initializes a new instance of the <see cref="BuildStyle"/> class
/// with parameters copied from the specified instance of the
/// <see cref="BuildStyle"/> class, a copy constructor.
/// </summary>
/// <param name="source">
/// An instance of the <see cref="BuildStyle"/> class from which the
/// initialization parameters or values will be copied.
/// </param>
/// <exception cref="ArgumentNullException">
/// If the parameter <paramref name="source"/> is <see langword="null"/>.
/// </exception>
public BuildStyle(BuildStyle source)
: base(source)
{
_styleDir = source._styleDir;
_styleName = source._styleName;
_stylePresentation = source._stylePresentation;
_styleType = source._styleType;
_scripts = source._scripts;
_snippets = source._snippets;
_styleSheets = source._styleSheets;
_mathPackages = source._mathPackages;
_mathCommands = source._mathCommands;
}
public BuildStyle this[BuildStyleType styleType]
{
get
{
for (int i = 0; i < this.Count; i++)
{
BuildStyle style = this[i];
if (style.StyleType == styleType)
{
return(style);
}
}
return(null);
}
}
private void OptimizeStyles(BuildContext context)
{
if (!_optimizeStyle)
{
return;
}
BuildSettings settings = context.Settings;
BuildStyleType styleType = settings.Style.StyleType;
// Currently, only the classic style is available and optimized...
if (styleType == BuildStyleType.ClassicWhite ||
styleType == BuildStyleType.ClassicBlue)
{
this.OptimizeClassicStyles(context);
}
}
public override BuildStep CreateFinalSteps(BuildGroup group)
{
if (group.GroupType != BuildGroupType.Reference)
{
throw new BuildException("The build engine requires reference group.");
}
BuildContext context = this.Context;
BuildSettings settings = this.Settings;
BuildGroupContext groupContext = context.GroupContexts[group.Id];
if (groupContext == null)
{
throw new BuildException(
"The group context is not provided, and it is required by the build system.");
}
string reflectionFile = groupContext["$ReflectionFile"];
string manifestFile = groupContext["$ManifestFile"];
string configFile = groupContext["$ConfigurationFile"];
string tocFile = groupContext["$TocFile"];
string sandcastleDir = context.StylesDirectory;
BuildStyleType outputStyle = settings.Style.StyleType;
string workingDir = context.WorkingDirectory;
// Assemble the help files using the BuildAssembler
// BuildAssembler.exe /config:Project.config manifest.xml
string application = Path.Combine(context.SandcastleToolsDirectory,
"BuildAssembler.exe");
string arguments = String.Format(" /config:{0} {1}",
configFile, manifestFile);
StepAssembler buildAssProcess = new StepAssembler(workingDir,
application, arguments);
buildAssProcess.Group = group;
buildAssProcess.LogTitle = String.Empty;
buildAssProcess.Message = "For the group: " + group.Name;
buildAssProcess.CopyrightNotice = 2;
return(buildAssProcess);
}
/// <summary>
/// Initializes a new instance of the <see cref="BuildStyle"/> class with
/// the specified style type.
/// </summary>
/// <param name="type">
/// An enumeration of the type <see cref="BuildStyleType"/> specifying the type
/// of the transformation and presentation style.
/// </param>
public BuildStyle(BuildStyleType type)
{
_styleType = type;
_scripts = new ScriptContent("CommonScripts");
_styleSheets = new StyleSheetContent("CommonStyleSheets");
_snippets = new SnippetContent("CommonSnippets");
_mathPackages = new MathPackageContent();
_mathCommands = new MathCommandContent();
string sandAssistDir = Path.GetDirectoryName(
Assembly.GetExecutingAssembly().Location);
string codeStyleFile = Path.Combine(sandAssistDir,
@"Styles\IrisModifiedVS.css");
string assistStyleFile = Path.Combine(sandAssistDir,
String.Format(@"Styles\{0}\SandAssist.css",
BuildStyle.StyleFolder(type)));
StyleSheetItem codeStyle = new StyleSheetItem("CodeStyle",
codeStyleFile);
codeStyle.Condition = "CodeHighlight";
_styleSheets.Add(codeStyle);
StyleSheetItem assistStyle = new StyleSheetItem("AssistStyle",
assistStyleFile);
_styleSheets.Add(assistStyle);
string assistScriptFile = Path.Combine(sandAssistDir,
String.Format(@"Scripts\{0}\SandAssist.js",
BuildStyle.StyleFolder(type)));
ScriptItem assistScript = new ScriptItem("AssistScripts",
assistScriptFile);
_scripts.Add(assistScript);
}
private void CreateReflectionSteps(BuildMultiStep listSteps,
ReferenceGroup group, string sandcastleDir, string helpStyle)
{
Debug.Assert(_engineSettings != null);
if (_engineSettings == null)
{
return;
}
BuildContext context = this.Context;
BuildSettings settings = this.Settings;
ReferenceGroupContext groupContext =
context.GroupContexts[group.Id] as ReferenceGroupContext;
if (groupContext == null)
{
throw new BuildException(
"The group context is not provided, and it is required by the build system.");
}
string workingDir = context.WorkingDirectory;
ReferenceContent content = group.Content;
string assemblyDir = Path.Combine(workingDir, groupContext.AssemblyFolder);
string dependencyDir = Path.Combine(workingDir, groupContext.DependencyFolder);
DependencyContent dependencies = content.Dependencies;
string reflectionFile = groupContext["$ReflectionFile"];
string manifestFile = groupContext["$ManifestFile"];
string refBuilderFile = groupContext["$ReflectionBuilderFile"];
string tocFile = groupContext["$TocFile"];
BuildStyleType outputStyle = settings.Style.StyleType;
string tempText = null;
string arguments = null;
string application = null;
bool ripOldApis = true;
string assemblyFiles = null;
string dependencyFiles = null;
string outputFile = null;
string configurationFile = null;
ReferenceVisibilityConfiguration visibility =
_engineSettings.Visibility;
Debug.Assert(visibility != null);
// 1. Create the reflection and the manifest
StringBuilder textBuilder = new StringBuilder();
if (group.IsSingleVersion)
{
// Call MRefBuilder to generate the reflection...
// MRefBuilder Assembly.dll
// /out:reflection.org /config:MRefBuilder.config
// /internal-
application = Path.Combine(context.SandcastleToolsDirectory,
"MRefBuilder.exe");
assemblyFiles = String.Format(@"{0}\*.*", assemblyDir);
dependencyFiles = String.Format(@"{0}\*.*", dependencyDir);
outputFile = Path.ChangeExtension(reflectionFile, ".ver");
configurationFile = Path.Combine(workingDir, refBuilderFile);
textBuilder.Append(assemblyFiles);
textBuilder.Append(" /dep:" + dependencyFiles);
textBuilder.AppendFormat(" /out:{0} /config:{1}",
outputFile, refBuilderFile);
if (visibility != null && visibility.IncludeInternalsMembers)
{
textBuilder.Append(" /internal+");
}
else
{
textBuilder.Append(" /internal-");
}
arguments = textBuilder.ToString();
outputFile = Path.Combine(workingDir, outputFile);
}
else
{
// Call the VersionBuilder to create the combined reflection file...
application = Path.Combine(context.SandcastleToolsDirectory,
"VersionBuilder.exe");
textBuilder.AppendFormat(" /config:{0} /out:{1}",
groupContext["$ApiVersionsBuilderFile"],
Path.ChangeExtension(reflectionFile, ".org"));
configurationFile = Path.Combine(workingDir,
groupContext["$ApiVersionsBuilderFile"]);
ReferenceVersionInfo versionInfo = group.VersionInfo;
ripOldApis = versionInfo.RipOldApis;
if (ripOldApis)
{
textBuilder.Append(" /rip+");
}
else
{
textBuilder.Append(" /rip-");
}
arguments = textBuilder.ToString();
}
StepReflectionBuilder refBuilder = new StepReflectionBuilder(workingDir,
application, arguments);
refBuilder.Group = group;
refBuilder.LogTitle = String.Empty;
refBuilder.Message = "Creating XML-formatted reflection information.";
refBuilder.CopyrightNotice = 2;
// For the direct use of the Sandcastle library, we need the
// following parameters...
refBuilder.RipOldApis = ripOldApis;
refBuilder.DocumentInternals =
(visibility != null && visibility.IncludeInternalsMembers);
refBuilder.ConfigurationFile = configurationFile;
refBuilder.ReflectionFile = outputFile;
refBuilder.AssemblyFiles.Add(assemblyFiles);
refBuilder.DependencyFiles.Add(dependencyFiles);
listSteps.Add(refBuilder);
textBuilder.Length = 0;
// 2. Create the reflection and comment refining step...
StepReferenceRefine referenceRefine =
new StepReferenceRefine(workingDir);
referenceRefine.LogTitle = String.Empty;
referenceRefine.Message = "Refining the reflection files - filtering and cleaning";
referenceRefine.Group = group;
listSteps.Add(referenceRefine);
textBuilder.Length = 0;
// 3. Apply Transforms
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl"
// reflection.org
// /xsl:"%DXROOT%\ProductionTransforms\AddFriendlyFilenames.xsl"
// /out:reflection.xml /arg:IncludeAllMembersTopic=true
// /arg:IncludeInheritedOverloadTopics=true /arg:project=Project
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
string prodPath = Path.Combine(sandcastleDir, "ProductionTransforms");
string textTemp = String.Empty;
if (group.EnableXmlnsForXaml)
{
textTemp = Path.Combine(prodPath, "AddXamlSyntaxData.xsl");
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
}
if (outputStyle == BuildStyleType.ClassicWhite ||
outputStyle == BuildStyleType.ClassicBlue)
{
textTemp = Path.Combine(prodPath, "ApplyVSDocModel.xsl");
}
else if (outputStyle == BuildStyleType.Lightweight)
{
}
else if (outputStyle == BuildStyleType.ScriptFree)
{
}
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
ReferenceNamingMethod namingMethod = _engineSettings.Naming;
if (namingMethod == ReferenceNamingMethod.Guid)
{
textTemp = Path.Combine(prodPath, "AddGuidFilenames.xsl");
}
else if (namingMethod == ReferenceNamingMethod.MemberName)
{
textTemp = Path.Combine(prodPath, "AddFriendlyFilenames.xsl");
}
else
{
textTemp = Path.Combine(prodPath, "AddGuidFilenames.xsl");
}
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
textBuilder.Append(" " + Path.ChangeExtension(reflectionFile, ".org"));
textBuilder.AppendFormat(" /out:{0}", reflectionFile);
textBuilder.AppendFormat(" /arg:IncludeAllMembersTopic={0}",
_engineSettings.IncludeAllMembersTopic ? "true" : "false");
textBuilder.AppendFormat(" /arg:IncludeInheritedOverloadTopics={0}",
_engineSettings.IncludeInheritedOverloadTopics ? "true" : "false");
bool rootContainer = _engineSettings.RootNamespaceContainer;
string rootTitle = group.RootNamespaceTitle;
if (rootContainer && !String.IsNullOrEmpty(rootTitle))
{
textBuilder.Append(" /arg:project=Project");
// Indicate that this reference group is rooted...
groupContext["$IsRooted"] = Boolean.TrueString;
}
arguments = textBuilder.ToString();
StepReferenceModel applyDocProcess = new StepReferenceModel(
workingDir, application, arguments);
applyDocProcess.Group = group;
applyDocProcess.LogTitle = String.Empty;
applyDocProcess.Message = "Xsl Transformation - Applying model and adding filenames";
applyDocProcess.CopyrightNotice = 2;
listSteps.Add(applyDocProcess);
textBuilder.Length = 0;
// 4. and finally the manifest...
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\ReflectionToManifest.xsl"
// reflection.xml /out:manifest.xml
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
textTemp = Path.Combine(prodPath, "ReflectionToManifest.xsl");
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textBuilder.AppendFormat(" {0} /out:{1}", reflectionFile, manifestFile);
arguments = textBuilder.ToString();
StepReferenceManifest manifestProcess = new StepReferenceManifest(
workingDir, application, arguments);
manifestProcess.Group = group;
manifestProcess.LogTitle = String.Empty;
manifestProcess.Message = "Xsl Transformation - Reflection to Manifest";
manifestProcess.CopyrightNotice = 2;
listSteps.Add(manifestProcess);
// 5. Create the reflection table of contents
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\createvstoc.xsl"
// reflection.xml /out:ApiToc.xml
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
if (outputStyle == BuildStyleType.ClassicWhite ||
outputStyle == BuildStyleType.ClassicBlue)
{
tempText = Path.Combine(sandcastleDir,
@"ProductionTransforms\CreateVSToc.xsl");
}
else if (outputStyle == BuildStyleType.Lightweight)
{
}
else if (outputStyle == BuildStyleType.ScriptFree)
{
}
arguments = String.Format("/xsl:\"{0}\" {1} /out:{2}",
tempText, reflectionFile, tocFile);
StepReferenceToc tocProcess = new StepReferenceToc(workingDir,
application, arguments);
tocProcess.LogTitle = String.Empty;
tocProcess.Message = "Xsl Transformation - Creating References TOC";
tocProcess.Group = group;
tocProcess.CopyrightNotice = 2;
listSteps.Add(tocProcess);
}
public void Create()
{
bool useCustomStyles = true;
BuildStyleType styleType = BuildStyleType.ClassicWhite;
_settings.WorkingDirectory = new BuildDirectoryPath(_workingDir);
_settings.CleanIntermediate = false;
_settings.ShowPreliminary = true;
_settings.Style.StyleType = styleType;
//_settings.SyntaxType = BuildSyntaxType.None;
_settings.HeaderText = "Header: This is the header text.";
_settings.FooterText = "Footer: This is the footer text.";
BuildFeedback feedBack = _settings.Feedback;
feedBack.CompanyName = "Sandcastle Assist";
feedBack.ProductName = "Sandcastle Helpers";
feedBack.EmailAddress = "*****@*****.**";
feedBack.FeedbackType = BuildFeedbackType.None;
feedBack.CopyrightText =
"Copyright © 2007-2008 Sandcastle Assist. All Rights Reserved.";
feedBack.CopyrightLink = "http://www.codeplex.com/SandAssist";
// Configure the logo image information...
feedBack.LogoEnabled = true; // show it...
feedBack.LogoImage = new BuildFilePath(Path.Combine(_sandAssistDir, "AssistLogo.jpg"));
feedBack.LogoWidth = 64;
feedBack.LogoHeight = 64;
feedBack.LogoPadding = 3;
feedBack.LogoText = "Sandcastle Assist";
feedBack.LogoLink = "http://www.codeplex.com/SandAssist";
feedBack.LogoAlignment = BuildLogoAlignment.Center;
feedBack.LogoPlacement = BuildLogoPlacement.Right;
// Configure the logging, we add some loggers by their names...
BuildLogging logging = _settings.Logging;
//logging.Verbosity = BuildLoggerVerbosity.Detailed;
//logging.AddLogger(XmlLogger.LoggerName);
//logging.AddLogger(HtmlLogger.LoggerName);
///logging.AddLogger(XamlLogger.LoggerName);
logging.AddLogger(ConsoleLogger.LoggerName);
BuildStyle style = _settings.Style;
// Add direct code snippet root folder...
SnippetContent snippets = style.Snippets;
snippets.Add(new SnippetItem(
Path.Combine(_sampleDir, "SampleSnippets")));
// Add some custom math packages and commands...
MathPackageContent mathPackages = style.MathPackages;
mathPackages.Add("picture", "calc");
mathPackages.Add("xy", "all", "knot", "poly");
MathCommandContent mathCommands = style.MathCommands;
mathCommands.Add(@"\quot",
@"\dfrac{\varphi \cdot X_{n, #1}}{\varphi_{#2} \times \varepsilon_{#1}}", 2);
mathCommands.Add(@"\exn", @"(x+\varepsilon_{#1})^{#1}", 1);
if (useCustomStyles)
{
string stylesDir = @"Presentations";
stylesDir = Path.GetFullPath(stylesDir);
if (Directory.Exists(stylesDir))
{
_settings.Style.Directory = new BuildDirectoryPath(stylesDir);
}
}
FormatChm chmFormat =
_settings.Formats[BuildFormatType.HtmlHelp1] as FormatChm;
if (chmFormat != null)
{
chmFormat.Enabled = true;
chmFormat.UseBinaryToc = false;
chmFormat.Indent = true;
}
//FormatHxs hxsFormat =
// _settings.Formats[BuildFormatType.HtmlHelp2] as FormatHxs;
//if (hxsFormat != null)
//{
// //hxsFormat.SeparateIndexFile = true;
// hxsFormat.Enabled = true;
// hxsFormat.Indent = true;
//}
//FormatMhv mhvFormat =
// _settings.Formats[BuildFormatType.HtmlHelp3] as FormatMhv;
//if (mhvFormat != null)
//{
// mhvFormat.Enabled = true;
// mhvFormat.Indent = true;
//}
//FormatWeb webFormat =
// _settings.Formats[BuildFormatType.WebHelp] as FormatWeb;
//if (webFormat != null)
//{
// webFormat.Enabled = true;
// webFormat.Indent = true;
//}
//_settings.HelpName = "HelpRegister";
//_settings.HelpTitle = "Sandcastle HelpRegister";
_settings.HelpName = "SandcastleHelpers";
_settings.HelpTitle = "Sandcastle Helpers Test Sample";
}
private bool CreateConfiguration(ReferenceGroup group)
{
BuildExceptions.NotNull(group, "group");
BuildContext context = this.Context;
BuildGroupContext groupContext = context.GroupContexts[group.Id];
if (groupContext == null)
{
throw new BuildException(
"The group context is not provided, and it is required by the build system.");
}
BuildLogger logger = context.Logger;
BuildSettings settings = context.Settings;
BuildStyle outputStyle = settings.Style;
BuildStyleType styleType = outputStyle.StyleType;
string workingDir = context.WorkingDirectory;
string configDir = settings.ConfigurationDirectory;
if (String.IsNullOrEmpty(workingDir))
{
if (logger != null)
{
logger.WriteLine(
"The working directory is required, it is not specified.",
BuildLoggerLevel.Error);
}
return(false);
}
string configFile = String.Empty;
string finalConfigFile = String.Empty;
if (!String.IsNullOrEmpty(configDir) && Directory.Exists(configDir))
{
configFile = Path.Combine(configDir,
BuildStyle.StyleFolder(styleType) + ".config");
finalConfigFile = Path.Combine(workingDir, groupContext["$ConfigurationFile"]);
}
if (!File.Exists(configFile))
{
configFile = String.Empty;
}
ReferenceConfigurator assembler = new ReferenceConfigurator();
try
{
assembler.Initialize(context);
// 3. Configure the build assembler...
if (!String.IsNullOrEmpty(configFile))
{
assembler.Configure(group, configFile, finalConfigFile);
_manifestFile = Path.Combine(workingDir,
groupContext["$ManifestFile"]);
_configurationFile = finalConfigFile;
}
}
finally
{
if (assembler != null)
{
assembler.Uninitialize();
}
}
return(true);
}
