/// <summary>
/// Initializes a new instance of the <see cref="ReferenceEngineSettings"/> class
/// with parameters copied from the specified instance of the
/// <see cref="ReferenceEngineSettings"/> class, a copy constructor.
/// </summary>
/// <param name="source">
/// An instance of the <see cref="ReferenceEngineSettings"/> 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 ReferenceEngineSettings(ReferenceEngineSettings source)
: base(source)
{
_topicLinks = source._topicLinks;
_refNaming = source._refNaming;
_webMvcSdkType = source._webMvcSdkType;
_refNamer = source._refNamer;
_rootContainer = source._rootContainer;
_embedScriptSharp = source._embedScriptSharp;
_includeAllMembersTopic = source._includeAllMembersTopic;
_includeInheritedOverloadTopics = source._includeInheritedOverloadTopics;
}
protected override void OnReadXml(XmlReader reader)
{
if (reader.IsEmptyElement)
{
return;
}
string startElement = reader.Name;
if (String.Equals(startElement, ReferenceSource.TagName,
StringComparison.OrdinalIgnoreCase))
{
string sourceName = reader.GetAttribute("name");
// For the link source...
if (String.Equals(sourceName, ReferenceLinkSource.SourceName,
StringComparison.OrdinalIgnoreCase))
{
if (_topicLinks == null)
{
_topicLinks = new BuildList <ReferenceLinkSource>();
}
ReferenceLinkSource linkSource = new ReferenceLinkSource();
linkSource.ReadXml(reader);
_topicLinks.Add(linkSource);
}
}
else if (String.Equals(startElement, "propertyGroup",
StringComparison.OrdinalIgnoreCase))
{
Debug.Assert(String.Equals(reader.GetAttribute("name"), "General"));
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 "namer":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_refNamer = (ReferenceNamer)Enum.Parse(
typeof(ReferenceNamer), tempText, true);
}
break;
case "naming":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_refNaming = (ReferenceNamingMethod)Enum.Parse(
typeof(ReferenceNamingMethod), tempText, true);
}
break;
case "rootnamespacecontainer":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_rootContainer = Convert.ToBoolean(tempText);
}
break;
case "embedscriptsharpframework":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_embedScriptSharp = Convert.ToBoolean(tempText);
}
break;
case "webmvcsdktype":
tempText = reader.ReadString();
if (!String.IsNullOrEmpty(tempText))
{
_webMvcSdkType = BuildSpecialSdkType.Parse(tempText);
}
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="ReferenceEngineSettings"/> class
/// with the default parameters.
/// </summary>
public ReferenceEngineSettings()
: base("Sandcastle.References.ReferenceEngineSettings", BuildEngineType.Reference)
{
_webMvcSdkType = BuildSpecialSdkType.Null;
_rootContainer = false;
_embedScriptSharp = true;
_includeAllMembersTopic = true;
_includeInheritedOverloadTopics = true;
_refNamer = ReferenceNamer.Orcas;
_refNaming = ReferenceNamingMethod.Guid;
IBuildNamedList <BuildConfiguration> configurations = this.Configurations;
if (configurations != null)
{
// For the ReferenceVisitors...
ReferenceCommentConfiguration comments =
new ReferenceCommentConfiguration();
ReferenceSpellCheckConfiguration spellCheck =
new ReferenceSpellCheckConfiguration();
ReferenceVisibilityConfiguration documentVisibility =
new ReferenceVisibilityConfiguration();
ReferenceXPathConfiguration pathDocumentVisibility =
new ReferenceXPathConfiguration();
pathDocumentVisibility.Enabled = false;
// For the ReferenceTocVistors...
ReferenceTocExcludeConfiguration excludeToc =
new ReferenceTocExcludeConfiguration();
ReferenceTocLayoutConfiguration layoutToc =
new ReferenceTocLayoutConfiguration();
configurations.Add(comments);
configurations.Add(documentVisibility);
configurations.Add(pathDocumentVisibility);
configurations.Add(spellCheck);
configurations.Add(excludeToc);
configurations.Add(layoutToc);
}
IBuildNamedList <BuildComponentConfiguration> componentConfigurations
= this.ComponentConfigurations;
if (componentConfigurations != null)
{
ReferencePreTransConfiguration preTrans =
new ReferencePreTransConfiguration();
ReferenceMissingTagsConfiguration missingTags =
new ReferenceMissingTagsConfiguration();
ReferenceAutoDocConfiguration autoDocument =
new ReferenceAutoDocConfiguration();
ReferenceIntelliSenseConfiguration intelliSense =
new ReferenceIntelliSenseConfiguration();
ReferencePlatformsConfiguration platforms =
new ReferencePlatformsConfiguration();
ReferenceCloneConfiguration cloneDocument =
new ReferenceCloneConfiguration();
ReferencePostTransConfiguration postTrans =
new ReferencePostTransConfiguration();
ReferenceCodeConfiguration codeComponent =
new ReferenceCodeConfiguration();
ReferenceMathConfiguration mathComponent =
new ReferenceMathConfiguration();
ReferenceMediaConfiguration mediaComponent =
new ReferenceMediaConfiguration();
ReferenceLinkConfiguration linkComponent =
new ReferenceLinkConfiguration();
ReferenceSharedConfiguration sharedComponent =
new ReferenceSharedConfiguration();
componentConfigurations.Add(preTrans);
componentConfigurations.Add(autoDocument);
componentConfigurations.Add(missingTags);
componentConfigurations.Add(intelliSense);
componentConfigurations.Add(platforms);
componentConfigurations.Add(cloneDocument);
componentConfigurations.Add(postTrans);
componentConfigurations.Add(codeComponent);
componentConfigurations.Add(mathComponent);
componentConfigurations.Add(mediaComponent);
componentConfigurations.Add(linkComponent);
componentConfigurations.Add(sharedComponent);
}
}
private bool Visit(string tocFilePath, BuildLogger logger)
{
_projectName = String.Empty;
_projectFile = String.Empty;
if (String.IsNullOrEmpty(tocFilePath))
{
return(false);
}
ReferenceTocLayoutType layoutType = _tocLayout.LayoutType;
if (layoutType == ReferenceTocLayoutType.None ||
layoutType == ReferenceTocLayoutType.Null ||
layoutType == ReferenceTocLayoutType.Flat)
{
return(false);
}
XPathDocument document = new XPathDocument(tocFilePath);
XPathNavigator documentNavigator = document.CreateNavigator();
XPathNavigator projectNode = documentNavigator.SelectSingleNode(
"topics/topic[starts-with(@id, 'R:')]");
if (projectNode != null)
{
_projectName = projectNode.GetAttribute("id", String.Empty);
if (_projectName == null)
{
_projectName = String.Empty;
}
_projectFile = projectNode.GetAttribute("file", String.Empty);
if (_projectFile == null)
{
_projectFile = String.Empty;
}
}
XPathNavigator rootNode = projectNode;
if (rootNode == null)
{
rootNode = documentNavigator.SelectSingleNode("topics");
}
XPathNodeIterator iterator = rootNode.Select(
"topic[starts-with(@id, 'N:')]");
if (iterator == null || iterator.Count == 0)
{
return(false);
}
_undocumentedNodes =
new List <KeyValuePair <string, HierarchicalTocNode> >();
_namingMethod = this.EngineSettings.Naming;
_tocFilePath = tocFilePath;
_dicNavigators = new BuildDictionary <XPathNavigator>();
if (layoutType == ReferenceTocLayoutType.Hierarchical)
{
_tocContents = new HierarchicalTocContent();
_tocContents.BeginItems(_projectName, _projectFile);
foreach (XPathNavigator navigator in iterator)
{
string nsText = navigator.GetAttribute("id", String.Empty);
if (!String.IsNullOrEmpty(nsText) && nsText.Length > 2)
{
nsText = nsText.Substring(2);
string projName = navigator.GetAttribute("project", String.Empty);
string fileName = navigator.GetAttribute("file", String.Empty);
if (_tocContents.AddItem(nsText, projName, fileName))
{
_dicNavigators.Add(nsText, navigator.Clone());
}
}
}
_tocContents.EndItems();
}
else if (layoutType == ReferenceTocLayoutType.Custom)
{
_tocContents = this.Group.Content.HierarchicalToc;
if (_tocContents != null)
{
foreach (XPathNavigator navigator in iterator)
{
string nsText = navigator.GetAttribute("id", String.Empty);
if (!String.IsNullOrEmpty(nsText) && nsText.Length > 2)
{
nsText = nsText.Substring(2);
string projName = navigator.GetAttribute("project", String.Empty);
string fileName = navigator.GetAttribute("file", String.Empty);
_dicNavigators.Add(nsText, navigator.Clone());
}
}
}
}
if (_tocContents == null)
{
return(false);
}
_rootNode = _tocContents.RootNode;
return(_rootNode != null);
}
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);
}
