void WriteType(FrameworkVersion version, TypeWrapper type)
{
var writer = new ClassWriter(this, version, type);
writer.Write();
foreach (var item in type.GetConstructors().Where(x => x.IsPublic))
{
var itemWriter = new ConstructorWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetMethodsToDocument())
{
// If a method is in another namespace, it is inherited and should not be overwritten
if (item.DeclaringType.Namespace == type.Namespace)
{
var itemWriter = new MethodWriter(this, version, item);
itemWriter.Write();
}
}
foreach (var item in type.GetEvents())
{
// If an event is in another namespace, it is inherited and should not be overwritten
if (item.DeclaringType.Namespace == type.Namespace)
{
var itemWriter = new EventWriter(this, version, item);
itemWriter.Write();
}
}
}
/// <summary>
/// Generates the documentation for the artifacts represented by this
/// manifest, starting at the namespace(s) in the assembly and working
/// down through the type hierarchy. Types that exist in the deferable
/// namespaces will be processed later in generation, when the awssdk.core
/// assembly is processed.
/// </summary>
/// <param name="deferrableTypes">
/// Collection for types in service assemblies that we want to defer processing
/// on until we process awssdk.core.
/// </param>
/// <param name="tocWriter">
/// Toc generation handler to which each processed namespace is registered
/// </param>
public void Generate(DeferredTypesProvider deferrableTypes, TOCWriter tocWriter)
{
Trace.WriteLine($"\tgenerating from {Options.Platform}/{Path.GetFileName(AssemblyPath)}");
// load the assembly and ndoc dataset for the service we're about to generate; assuming
// they contain no deferrable types we'll release them when done
var discardAssemblyOnExit = true;
foreach (var platform in AllPlatforms)
{
NDocUtilities.LoadDocumentation(AssemblyName, ServiceName, platform, Options);
}
var namespaceNames = ManifestAssemblyContext.SdkAssembly.GetNamespaces();
var frameworkVersion = FrameworkVersion.FromPlatformFolder(Options.Platform);
var processed = 0;
foreach (var namespaceName in namespaceNames)
{
// when processing awssdk.core, we don't get handed a collection to hold
// deferrable types
if (deferrableTypes != null)
{
if (deferrableTypes.Namespaces.Contains(namespaceName))
{
var types = ManifestAssemblyContext.SdkAssembly.GetTypesForNamespace(namespaceName);
if (types.Any())
{
Trace.WriteLine($"\t\tdeferring processing of types in namespace {namespaceName} for {Path.GetFileName(AssemblyPath)}");
deferrableTypes.AddTypes(types);
discardAssemblyOnExit = false;
}
continue;
}
}
WriteNamespace(frameworkVersion, namespaceName);
tocWriter.BuildNamespaceToc(namespaceName, ManifestAssemblyContext.SdkAssembly);
Trace.WriteLine($"\t\t{namespaceName} processed ({++processed} of {namespaceNames.Count()})");
}
if (discardAssemblyOnExit)
{
// release artifact roots for future GC collections to operate on
foreach (var platform in AllPlatforms)
{
NDocUtilities.UnloadDocumentation(ServiceName, platform);
}
ManifestAssemblyContext.Dispose();
ManifestAssemblyContext = null;
}
}
void WriteNamespace(FrameworkVersion version, string namespaceName)
{
var writer = new NamespaceWriter(this, version, namespaceName);
writer.Write();
foreach (var type in ManifestAssemblyContext.SdkAssembly.GetTypesForNamespace(namespaceName))
{
WriteType(version, type);
}
}
void WriteNamespace(FrameworkVersion version, string namespaceName)
{
var writer = new NamespaceWriter(this, version, namespaceName);
writer.Write();
foreach (var type in AssemblyWrapper.GetTypesForNamespace(namespaceName))
{
WriteType(version, type);
}
}
/// <summary>
/// Generates the documentation for the artifacts represented by this
/// manifest, starting at the namespace(s) in the assembly and working
/// down through the type hierarchy.
/// </summary>
public void Generate()
{
Trace.WriteLine(String.Format("\tgenerating from {0}/{1}", Options.Platform, Path.GetFileName(AssemblyPath)));
var namespaceNames = AssemblyWrapper.GetNamespaces();
var frameworkVersion = FrameworkVersion.FromPlatformFolder(Options.Platform);
var processed = 0;
foreach (var namespaceName in namespaceNames)
{
WriteNamespace(frameworkVersion, namespaceName);
Trace.WriteLine(String.Format("\t\t{0} processed ({1} of {2})", namespaceName, ++processed, namespaceNames.Count()));
}
}
public void GetHelpURL(FrameworkVersion version, out string url, out string target)
{
target = "";
url = null;
if (IsSystemNamespace)
{
// msdn urls for generic collections are not predictable, so
// we elect to output as simple text
if (!this.IsGenericType)
{
target = "target=_new";
url = string.Format(NDocUtilities.MSDN_TYPE_URL_PATTERN, this.GetDisplayName(true).ToLower());
}
}
else if (IsAmazonNamespace)
{
// don't know if reference is to a type in folder for namespace of declaring type we're
// processing, or in another namespace (folder), so jump to output root on the link
url = string.Format("../{0}/{1}",
GenerationManifest.OutputSubFolderFromNamespace(this.Namespace),
FilenameGenerator.GenerateFilename(this));
}
}
void WriteType(FrameworkVersion version, TypeWrapper type)
{
var writer = new ClassWriter(this, version, type);
writer.Write();
foreach (var item in type.GetConstructors().Where(x => x.IsPublic))
{
var itemWriter = new ConstructorWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetMethodsToDocument())
{
var itemWriter = new MethodWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetEvents())
{
var itemWriter = new EventWriter(this, version, item);
itemWriter.Write();
}
}
void WriteNamespace(FrameworkVersion version, string namespaceName)
{
var writer = new NamespaceWriter(this, version, namespaceName);
writer.Write();
foreach (var type in AssemblyWrapper.GetTypesForNamespace(namespaceName))
{
WriteType(version, type);
}
}
private static string DocBlobToHTML(XElement rootNode, AbstractTypeProvider typeProvider, FrameworkVersion version)
{
var reader = rootNode.CreateReader();
reader.MoveToContent();
var innerXml = reader.ReadInnerXml();
innerXml = innerXml.Replace("<summary>", "<p>");
innerXml = innerXml.Replace("</summary>", "</p>");
innerXml = innerXml.Replace("<para>", "<p>");
innerXml = innerXml.Replace("</para>", "</p>");
//innerText = innerText.Replace("<code", "<pre class=\"code-sample\">");
//innerText = innerText.Replace("</code>", "</pre>");
// scan for <see> and <seealso> cross-reference tags and replace with <a> links with the
// content - which // can be a cref indication to a typename, or a href.
var scanIndex = innerXml.IndexOf(crossReferenceOpeningTagText, StringComparison.Ordinal);
while (scanIndex >= 0)
{
var attrStart = innerXml.IndexOf(innerCrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var cref = ExtractCrefAttributeContent(innerXml, attrStart, out crossRefTagEndIndex);
var replacement = BaseWriter.CreateCrossReferenceTagReplacement(typeProvider, cref, version);
var oldCrossRefTag = innerXml.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerXml = innerXml.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
{
attrStart = innerXml.IndexOf(innerHrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var url = ExtractHrefAttributeContent(innerXml, attrStart, out crossRefTagEndIndex);
var replacement = string.Format("<a href=\"{0}\">{0}</a>", url);
var oldCrossRefTag = innerXml.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerXml = innerXml.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
{
scanIndex++;
}
}
scanIndex = innerXml.IndexOf(crossReferenceOpeningTagText, scanIndex, StringComparison.Ordinal);
}
return(innerXml);
}
public static string TransformDocumentationToHTML(XElement element, string rootNodeName, AssemblyWrapper assemblyWrapper, FrameworkVersion version)
{
if (element == null)
return string.Empty;
var rootNode = element.XPathSelectElement(rootNodeName);
if (rootNode == null)
return string.Empty;
//var crossRefTags = new[] { "see", "seealso" };
//foreach (var crossRefTag in crossRefTags)
//{
// var crossRefs = rootNode.Descendants(crossRefTag);
// if (crossRefs.Any())
// {
// foreach (var crossRef in crossRefs)
// {
// var typeName = BaseWriter.GetCrossReferenceTypeName(crossRef);
// string target;
// var url = BaseWriter.CrossReferenceTypeToUrl(assemblyWrapper, typeName, version, out target);
// var href = url != null ? string.Format("<a href=\"{0}\" {2}>{1}</a>", url, typeName, target) : typeName;
// crossRef.ReplaceWith(href);
// }
// }
//}
var reader = rootNode.CreateReader();
reader.MoveToContent();
var innerXml = reader.ReadInnerXml();
var innerText = innerXml;
innerText = innerText.Replace("<summary>", "<p>");
innerText = innerText.Replace("</summary>", "</p>");
innerText = innerText.Replace("<para>", "<p>");
innerText = innerText.Replace("</para>", "</p>");
//innerText = innerText.Replace("<code", "<pre class=\"code-sample\">");
//innerText = innerText.Replace("</code>", "</pre>");
// scan for <see> and <seealso> cross-reference tags and replace with <a> links with the
// content - which // can be a cref indication to a typename, or a href.
var scanIndex = innerText.IndexOf(crossReferenceOpeningTagText, StringComparison.Ordinal);
while (scanIndex >= 0)
{
var attrStart = innerText.IndexOf(innerCrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var cref = ExtractCrefAttributeContent(innerText, attrStart, out crossRefTagEndIndex);
var replacement = BaseWriter.CreateCrossReferenceTagReplacement(assemblyWrapper, cref, version);
var oldCrossRefTag = innerText.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerText = innerText.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
{
attrStart = innerText.IndexOf(innerHrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var url = ExtractHrefAttributeContent(innerText, attrStart, out crossRefTagEndIndex);
var replacement = string.Format("<a href=\"{0}\">{0}</a>", url);
var oldCrossRefTag = innerText.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerText = innerText.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
scanIndex++;
}
scanIndex = innerText.IndexOf(crossReferenceOpeningTagText, scanIndex, StringComparison.Ordinal);
}
return innerText;
}
public static string TransformDocumentationToHTML(XElement element, string rootNodeName, AssemblyWrapper assemblyWrapper, FrameworkVersion version)
{
if (element == null)
{
return(string.Empty);
}
var rootNode = element.XPathSelectElement(rootNodeName);
if (rootNode == null)
{
return(string.Empty);
}
//var crossRefTags = new[] { "see", "seealso" };
//foreach (var crossRefTag in crossRefTags)
//{
// var crossRefs = rootNode.Descendants(crossRefTag);
// if (crossRefs.Any())
// {
// foreach (var crossRef in crossRefs)
// {
// var typeName = BaseWriter.GetCrossReferenceTypeName(crossRef);
// string target;
// var url = BaseWriter.CrossReferenceTypeToUrl(assemblyWrapper, typeName, version, out target);
// var href = url != null ? string.Format("<a href=\"{0}\" {2}>{1}</a>", url, typeName, target) : typeName;
// crossRef.ReplaceWith(href);
// }
// }
//}
var reader = rootNode.CreateReader();
reader.MoveToContent();
var innerXml = reader.ReadInnerXml();
var innerText = innerXml;
innerText = innerText.Replace("<summary>", "<p>");
innerText = innerText.Replace("</summary>", "</p>");
innerText = innerText.Replace("<para>", "<p>");
innerText = innerText.Replace("</para>", "</p>");
//innerText = innerText.Replace("<code", "<pre class=\"code-sample\">");
//innerText = innerText.Replace("</code>", "</pre>");
// scan for <see> and <seealso> cross-reference tags and replace with <a> links with the
// content - which // can be a cref indication to a typename, or a href.
var scanIndex = innerText.IndexOf(crossReferenceOpeningTagText, StringComparison.Ordinal);
while (scanIndex >= 0)
{
var attrStart = innerText.IndexOf(innerCrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var cref = ExtractCrefAttributeContent(innerText, attrStart, out crossRefTagEndIndex);
var replacement = BaseWriter.CreateCrossReferenceTagReplacement(assemblyWrapper, cref, version);
var oldCrossRefTag = innerText.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerText = innerText.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
{
attrStart = innerText.IndexOf(innerHrefAttributeText, scanIndex, StringComparison.Ordinal);
if (attrStart >= 0)
{
int crossRefTagEndIndex;
var url = ExtractHrefAttributeContent(innerText, attrStart, out crossRefTagEndIndex);
var replacement = string.Format("<a href=\"{0}\">{0}</a>", url);
var oldCrossRefTag = innerText.Substring(scanIndex, crossRefTagEndIndex - scanIndex);
innerText = innerText.Replace(oldCrossRefTag, replacement);
scanIndex += replacement.Length;
}
else
{
scanIndex++;
}
}
scanIndex = innerText.IndexOf(crossReferenceOpeningTagText, scanIndex, StringComparison.Ordinal);
}
return(innerText);
}
public void GetHelpURL(FrameworkVersion version, out string url, out string target)
{
target = "";
url = null;
if (IsSystemNamespace)
{
// msdn urls for generic collections are not predictable, so
// we elect to output as simple text
if (!this.IsGenericType)
{
target = "target=_new";
url = string.Format(NDocUtilities.MSDN_TYPE_URL_PATTERN, this.GetDisplayName(true).ToLower());
}
}
else if (IsAmazonNamespace)
{
// don't know if reference is to a type in folder for namespace of declaring type we're
// processing, or in another namespace (folder), so jump to output root on the link
url = string.Format("../{0}/{1}",
GenerationManifest.OutputSubFolderFromNamespace(this.Namespace),
FilenameGenerator.GenerateFilename(this));
}
}
void WriteType(FrameworkVersion version, TypeWrapper type)
{
var writer = new ClassWriter(this, version, type);
writer.Write();
foreach (var item in type.GetConstructors().Where(x => x.IsPublic))
{
var itemWriter = new ConstructorWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetMethodsToDocument())
{
var itemWriter = new MethodWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetEvents())
{
var itemWriter = new EventWriter(this, version, item);
itemWriter.Write();
}
}
void WriteType(FrameworkVersion version, TypeWrapper type)
{
var writer = new ClassWriter(this, version, type);
writer.Write();
foreach (var item in type.GetConstructors().Where(x => x.IsPublic))
{
var itemWriter = new ConstructorWriter(this, version, item);
itemWriter.Write();
}
foreach (var item in type.GetMethodsToDocument())
{
// If a method is in another namespace, it is inherited and should not be overwritten
if (item.DeclaringType.Namespace == type.Namespace)
{
var itemWriter = new MethodWriter(this, version, item);
itemWriter.Write();
}
}
foreach (var item in type.GetEvents())
{
// If an event is in another namespace, it is inherited and should not be overwritten
if (item.DeclaringType.Namespace == type.Namespace)
{
var itemWriter = new EventWriter(this, version, item);
itemWriter.Write();
}
}
}
private static string DocBlobToHTML(XElement rootNode, AbstractTypeProvider typeProvider, FrameworkVersion version)
{
using (var textWriter = new StringWriter())
{
var writerSettings = new XmlWriterSettings {
OmitXmlDeclaration = true
};
using (var writer = XmlWriter.Create(textWriter, writerSettings))
{
var reader = rootNode.CreateReader();
while (reader.Read())
{
switch (reader.NodeType)
{
case XmlNodeType.Element:
// handle self-closing element, like <a />
// this must be read before any other reading is done
var selfClosingElement = reader.IsEmptyElement;
// element name substitution, if necessary
string elementName;
if (!NdocToHtmlElementMapping.TryGetValue(reader.LocalName, out elementName))
{
elementName = reader.LocalName;
}
// some elements can't be empty, use this variable for that
string emptyElementContents = null;
// start element
writer.WriteStartElement(elementName);
// copy over attributes
if (reader.HasAttributes)
{
for (int i = 0; i < reader.AttributeCount; i++)
{
reader.MoveToAttribute(i);
var attributeName = reader.Name;
var attributeValue = reader.Value;
var isCref = string.Equals(attributeName, crefAttributeName, StringComparison.Ordinal);
var isHref = string.Equals(attributeName, hrefAttributeName, StringComparison.Ordinal);
var isName = string.Equals(attributeName, nameAttributeName, StringComparison.Ordinal);
var writeAttribute = true;
if (isCref)
{
// replace cref with href
attributeName = hrefAttributeName;
// extract type name from cref value for emptyElementContents
var crefParts = attributeValue.Split(':');
if (crefParts.Length != 2)
{
throw new InvalidOperationException();
}
var typeName = crefParts[1];
var targetType = typeProvider.GetType(typeName);
if (targetType == null)
{
emptyElementContents = typeName;
//If the type cannot be found do not render out the href attribute.
//This will make it so things such as properties which we do not have
//specific doc pages for do not render as a broken link but we can still
//use the crefs in the code correctly.
writeAttribute = false;
}
else
{
emptyElementContents = targetType.CreateReferenceHtml(fullTypeName: true);
}
}
else if (isHref)
{
// extract href value for emptyElementContents
emptyElementContents = attributeValue;
}
else if (isName)
{
emptyElementContents = attributeValue;
}
if (writeAttribute)
{
writer.WriteAttributeString(attributeName, attributeValue);
}
}
}
// if this is a self-closing element, close it
if (selfClosingElement)
{
// write empty element contents, if any
if (!string.IsNullOrEmpty(emptyElementContents))
{
writer.WriteRaw(emptyElementContents);
}
// close element now
writer.WriteEndElement();
}
break;
case XmlNodeType.EndElement:
writer.WriteEndElement();
break;
case XmlNodeType.Text:
writer.WriteRaw(reader.Value);
break;
default:
throw new InvalidOperationException();
}
}
}
return(textWriter.ToString());
}
}
private static string SeeAlsoElementToHTML(XElement rootNode, AbstractTypeProvider typeProvider, FrameworkVersion version)
{
var reader = rootNode.CreateReader();
reader.MoveToContent();
var innerXml = reader.ReadInnerXml();
string content = "";
var href = rootNode.Attribute("href");
if (href != null)
{
content += string.Format(@"<div><a href=""{0}"" target=""_parent"" rel=""noopener noreferrer"">{1}</a></div>", href.Value, innerXml);
}
var cref = rootNode.Attribute("cref");
if (cref != null)
{
content += BaseWriter.CreateCrossReferenceTagReplacement(typeProvider, cref.Value, version);
}
return(content);
}
public static string TransformDocumentationToHTML(XElement element, string rootNodeName, AbstractTypeProvider typeProvider, FrameworkVersion version)
{
if (element == null)
{
return(string.Empty);
}
var rootNode = element.XPathSelectElement(rootNodeName);
if (rootNode == null)
{
return(string.Empty);
}
if (rootNodeName.Equals("seealso", StringComparison.OrdinalIgnoreCase))
{
return(SeeAlsoElementToHTML(rootNode, typeProvider, version));
}
else
{
return(DocBlobToHTML(rootNode, typeProvider, version));
}
}
