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