536cd135cc
Former-commit-id: 5624ac747d633e885131e8349322922b6a59baaa
497 lines
16 KiB
C#
497 lines
16 KiB
C#
using System;
|
|
using System.Collections;
|
|
using System.Collections.Generic;
|
|
using System.Diagnostics;
|
|
using System.IO;
|
|
using System.Linq;
|
|
using System.Reflection;
|
|
using System.Text;
|
|
using System.Xml;
|
|
using System.Xml.Xsl;
|
|
using System.Xml.XPath;
|
|
|
|
using Mono.Documentation;
|
|
using Mono.Options;
|
|
|
|
[assembly: AssemblyTitle("Monodocs-to-HTML")]
|
|
[assembly: AssemblyCopyright("Copyright (c) 2004 Joshua Tauberer <tauberer@for.net>, released under the GPL.")]
|
|
[assembly: AssemblyDescription("Convert Monodoc XML documentation to static HTML.")]
|
|
|
|
namespace Mono.Documentation {
|
|
|
|
class MDocToHtmlConverterOptions {
|
|
public string dest;
|
|
public string ext = "html";
|
|
public string onlytype;
|
|
public string template;
|
|
public bool dumptemplate;
|
|
public bool forceUpdate;
|
|
public HashSet<string> versions = new HashSet<string> ();
|
|
}
|
|
|
|
class MDocToHtmlConverter : MDocCommand {
|
|
|
|
static Dictionary<string, string[]> profiles = new Dictionary<string, string[]>() {
|
|
// FxVersions----- VsVersions-----
|
|
{ "monotouch", new[]{"0.0.0.0", "2.0.5.0" } },
|
|
{ "net_1_0", new[]{"1.0.3300.0", "7.0.3300.0"} },
|
|
{ "net_1_1", new[]{"1.0.5000.0", "7.0.5000.0"} },
|
|
{ "net_2_0", new[]{"2.0.0.0", "8.0.0.0"} },
|
|
{ "net_3_0", new[]{"2.0.0.0", "3.0.0.0", "8.0.0.0"} },
|
|
{ "net_3_5", new[]{"2.0.0.0", "3.0.0.0", "3.5.0.0", "8.0.0.0"} },
|
|
{ "net_4_0", new[]{"4.0.0.0" } },
|
|
{ "silverlight", new[]{"2.0.5.0", "9.0.0.0"} },
|
|
};
|
|
|
|
public override void Run (IEnumerable<string> args)
|
|
{
|
|
opts = new MDocToHtmlConverterOptions ();
|
|
var p = new OptionSet () {
|
|
{ "default-template",
|
|
"Writes the default XSLT to stdout.",
|
|
v => opts.dumptemplate = v != null },
|
|
{ "ext=",
|
|
"The file {EXTENSION} to use for created files. "+
|
|
"This defaults to \"html\".",
|
|
v => opts.ext = v },
|
|
{ "force-update",
|
|
"Always generate new files. If not specified, will only generate a " +
|
|
"new file if the source .xml file is newer than the current output " +
|
|
"file.",
|
|
v => opts.forceUpdate = v != null },
|
|
{ "o|out=",
|
|
"The {DIRECTORY} to place the generated files and directories.",
|
|
v => opts.dest = v },
|
|
{ "template=",
|
|
"An XSLT {FILE} to use to generate the created " +
|
|
"files.If not specified, uses the template generated by " +
|
|
"--default-template.",
|
|
v => opts.template = v },
|
|
{ "with-profile=",
|
|
"The .NET {PROFILE} to generate documentation for. This is " +
|
|
"equivalent to using --with-version for all of the " +
|
|
"versions that a profile uses. Valid profiles are:\n " +
|
|
string.Join ("\n ", profiles.Keys.OrderBy (v => v).ToArray ()),
|
|
v => {
|
|
if (!profiles.ContainsKey (v))
|
|
throw new ArgumentException (string.Format ("Unsupported profile '{0}'.", v));
|
|
foreach (var ver in profiles [v.ToLowerInvariant ()])
|
|
opts.versions.Add (ver);
|
|
} },
|
|
{ "with-version=",
|
|
"The assembly {VERSION} to generate documentation for. This allows " +
|
|
"display of a subset of types/members that correspond to the given " +
|
|
"assembly version. May be specified multiple times. " +
|
|
"If not specified, all versions are displayed.",
|
|
v => opts.versions.Add (v) }
|
|
};
|
|
List<string> extra = Parse (p, args, "export-html",
|
|
"[OPTIONS]+ DIRECTORIES",
|
|
"Export mdoc documentation within DIRECTORIES to HTML.");
|
|
if (extra == null)
|
|
return;
|
|
if (opts.dumptemplate)
|
|
DumpTemplate ();
|
|
else
|
|
ProcessDirectories (extra);
|
|
opts.onlytype = "ignore"; // remove warning about unused member
|
|
}
|
|
|
|
static MDocToHtmlConverterOptions opts;
|
|
|
|
void ProcessDirectories (List<string> sourceDirectories)
|
|
{
|
|
if (sourceDirectories.Count == 0 || opts.dest == null || opts.dest == "")
|
|
throw new ApplicationException("The source and dest options must be specified.");
|
|
|
|
Directory.CreateDirectory(opts.dest);
|
|
|
|
// Load the stylesheets, overview.xml, and resolver
|
|
|
|
XslCompiledTransform overviewxsl = LoadTransform("overview.xsl", sourceDirectories);
|
|
XslCompiledTransform stylesheet = LoadTransform("stylesheet.xsl", sourceDirectories);
|
|
XslCompiledTransform template;
|
|
if (opts.template == null) {
|
|
template = LoadTransform("defaulttemplate.xsl", sourceDirectories);
|
|
} else {
|
|
try {
|
|
XmlDocument templatexsl = new XmlDocument();
|
|
templatexsl.Load(opts.template);
|
|
template = new XslCompiledTransform (DebugOutput);
|
|
template.Load(templatexsl);
|
|
} catch (Exception e) {
|
|
throw new ApplicationException("There was an error loading " + opts.template, e);
|
|
}
|
|
}
|
|
|
|
XmlDocument overview = GetOverview (sourceDirectories);
|
|
|
|
ArrayList extensions = GetExtensionMethods (overview);
|
|
|
|
// Create the master page
|
|
XsltArgumentList overviewargs = new XsltArgumentList();
|
|
overviewargs.AddParam("Index", "", overview.CreateNavigator ());
|
|
|
|
var regenIndex = ShouldRegenIndexes (opts, overview, sourceDirectories);
|
|
if (regenIndex) {
|
|
overviewargs.AddParam("ext", "", opts.ext);
|
|
overviewargs.AddParam("basepath", "", "./");
|
|
Generate(overview, overviewxsl, overviewargs, opts.dest + "/index." + opts.ext, template, sourceDirectories);
|
|
overviewargs.RemoveParam("basepath", "");
|
|
}
|
|
overviewargs.AddParam("basepath", "", "../");
|
|
|
|
// Create the namespace & type pages
|
|
|
|
XsltArgumentList typeargs = new XsltArgumentList();
|
|
typeargs.AddParam("ext", "", opts.ext);
|
|
typeargs.AddParam("basepath", "", "../");
|
|
typeargs.AddParam("Index", "", overview.CreateNavigator ());
|
|
|
|
foreach (XmlElement ns in overview.SelectNodes("Overview/Types/Namespace")) {
|
|
string nsname = ns.GetAttribute("Name");
|
|
|
|
if (opts.onlytype != null && !opts.onlytype.StartsWith(nsname + "."))
|
|
continue;
|
|
|
|
System.IO.DirectoryInfo d = new System.IO.DirectoryInfo(opts.dest + "/" + nsname);
|
|
if (!d.Exists) d.Create();
|
|
|
|
// Create the NS page
|
|
string nsDest = opts.dest + "/" + nsname + "/index." + opts.ext;
|
|
if (regenIndex) {
|
|
overviewargs.AddParam("namespace", "", nsname);
|
|
Generate(overview, overviewxsl, overviewargs, nsDest, template, sourceDirectories);
|
|
overviewargs.RemoveParam("namespace", "");
|
|
}
|
|
|
|
foreach (XmlElement ty in ns.SelectNodes("Type")) {
|
|
string typename, typefile, destfile;
|
|
GetTypePaths (opts, ty, out typename, out typefile, out destfile);
|
|
|
|
if (DestinationIsNewer (typefile, destfile))
|
|
// target already exists, and is newer. why regenerate?
|
|
continue;
|
|
|
|
XmlDocument typexml = new XmlDocument();
|
|
typexml.Load(typefile);
|
|
PreserveMembersInVersions (typexml);
|
|
if (extensions != null) {
|
|
DocLoader loader = CreateDocLoader (overview);
|
|
XmlDocUtils.AddExtensionMethods (typexml, extensions, loader);
|
|
}
|
|
|
|
Console.WriteLine(nsname + "." + typename);
|
|
|
|
Generate(typexml, stylesheet, typeargs, destfile, template, sourceDirectories);
|
|
}
|
|
}
|
|
}
|
|
|
|
private static ArrayList GetExtensionMethods (XmlDocument doc)
|
|
{
|
|
XmlNodeList extensions = doc.SelectNodes ("/Overview/ExtensionMethods/*");
|
|
if (extensions.Count == 0)
|
|
return null;
|
|
ArrayList r = new ArrayList (extensions.Count);
|
|
foreach (XmlNode n in extensions)
|
|
r.Add (n);
|
|
return r;
|
|
}
|
|
|
|
static bool ShouldRegenIndexes (MDocToHtmlConverterOptions opts, XmlDocument overview, List<string> sourceDirectories)
|
|
{
|
|
string overviewDest = opts.dest + "/index." + opts.ext;
|
|
if (sourceDirectories.Any (
|
|
d => !DestinationIsNewer (Path.Combine (d, "index.xml"), overviewDest)))
|
|
return true;
|
|
|
|
foreach (XmlElement type in overview.SelectNodes("Overview/Types/Namespace/Type")) {
|
|
string _, srcfile, destfile;
|
|
GetTypePaths (opts, type, out _, out srcfile, out destfile);
|
|
|
|
if (srcfile == null || destfile == null)
|
|
continue;
|
|
if (DestinationIsNewer (srcfile, destfile))
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
static void GetTypePaths (MDocToHtmlConverterOptions opts, XmlElement type, out string typename, out string srcfile, out string destfile)
|
|
{
|
|
srcfile = null;
|
|
destfile = null;
|
|
|
|
string nsname = type.ParentNode.Attributes ["Name"].Value;
|
|
string typefilebase = type.GetAttribute("Name");
|
|
string sourceDir = type.GetAttribute("SourceDirectory");
|
|
typename = type.GetAttribute("DisplayName");
|
|
if (typename.Length == 0)
|
|
typename = typefilebase;
|
|
|
|
if (opts.onlytype != null && !(nsname + "." + typename).StartsWith(opts.onlytype))
|
|
return;
|
|
|
|
srcfile = CombinePath (sourceDir, nsname, typefilebase + ".xml");
|
|
if (srcfile == null)
|
|
return;
|
|
|
|
destfile = CombinePath (opts.dest, nsname, typefilebase + "." + opts.ext);
|
|
}
|
|
|
|
private static void DumpTemplate() {
|
|
Stream s = Assembly.GetExecutingAssembly().GetManifestResourceStream("defaulttemplate.xsl");
|
|
Stream o = Console.OpenStandardOutput ();
|
|
byte[] buf = new byte[1024];
|
|
int r;
|
|
while ((r = s.Read (buf, 0, buf.Length)) > 0) {
|
|
o.Write (buf, 0, r);
|
|
}
|
|
}
|
|
|
|
private static void Generate(XmlDocument source, XslCompiledTransform transform, XsltArgumentList args, string output, XslCompiledTransform template, List<string> sourceDirectories) {
|
|
using (TextWriter textwriter = new StreamWriter(new FileStream(output, FileMode.Create))) {
|
|
XmlTextWriter writer = new XmlTextWriter(textwriter);
|
|
writer.Formatting = Formatting.Indented;
|
|
writer.Indentation = 2;
|
|
writer.IndentChar = ' ';
|
|
|
|
try {
|
|
var intermediate = new StringBuilder ();
|
|
transform.Transform (
|
|
new XmlNodeReader (source),
|
|
args,
|
|
XmlWriter.Create (intermediate, transform.OutputSettings),
|
|
new ManifestResourceResolver(sourceDirectories.ToArray ()));
|
|
template.Transform (
|
|
XmlReader.Create (new StringReader (intermediate.ToString ())),
|
|
new XsltArgumentList (),
|
|
new XhtmlWriter (writer),
|
|
null);
|
|
} catch (Exception e) {
|
|
throw new ApplicationException("An error occured while generating " + output, e);
|
|
}
|
|
}
|
|
}
|
|
|
|
private XslCompiledTransform LoadTransform(string name, List<string> sourceDirectories) {
|
|
try {
|
|
XmlDocument xsl = new XmlDocument();
|
|
xsl.Load(Assembly.GetExecutingAssembly().GetManifestResourceStream(name));
|
|
|
|
if (name == "overview.xsl") {
|
|
// bit of a hack. overview needs the templates in stylesheet
|
|
// for doc formatting, and rather than write a resolver, I'll
|
|
// just do the import for it.
|
|
|
|
XmlNode importnode = xsl.DocumentElement.SelectSingleNode("*[name()='xsl:include']");
|
|
xsl.DocumentElement.RemoveChild(importnode);
|
|
|
|
XmlDocument xsl2 = new XmlDocument();
|
|
xsl2.Load(Assembly.GetExecutingAssembly().GetManifestResourceStream("stylesheet.xsl"));
|
|
foreach (XmlNode node in xsl2.DocumentElement.ChildNodes)
|
|
xsl.DocumentElement.AppendChild(xsl.ImportNode(node, true));
|
|
}
|
|
|
|
XslCompiledTransform t = new XslCompiledTransform (DebugOutput);
|
|
t.Load (
|
|
xsl,
|
|
XsltSettings.TrustedXslt,
|
|
new ManifestResourceResolver (sourceDirectories.ToArray ()));
|
|
|
|
return t;
|
|
} catch (Exception e) {
|
|
throw new ApplicationException("Error loading " + name + " from internal resource", e);
|
|
}
|
|
}
|
|
|
|
private static DocLoader CreateDocLoader (XmlDocument overview)
|
|
{
|
|
Hashtable docs = new Hashtable ();
|
|
DocLoader loader = delegate (string s) {
|
|
XmlDocument d = null;
|
|
if (!docs.ContainsKey (s)) {
|
|
foreach (XmlNode n in overview.SelectNodes ("//Type")) {
|
|
string ns = n.ParentNode.Attributes ["Name"].Value;
|
|
string t = n.Attributes ["Name"].Value;
|
|
string sd = n.Attributes ["SourceDirectory"].Value;
|
|
if (s == ns + "." + t.Replace ("+", ".")) {
|
|
string f = CombinePath (sd, ns, t + ".xml");
|
|
if (File.Exists (f)) {
|
|
d = new XmlDocument ();
|
|
d.Load (f);
|
|
}
|
|
docs.Add (s, d);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
else
|
|
d = (XmlDocument) docs [s];
|
|
return d;
|
|
};
|
|
return loader;
|
|
}
|
|
|
|
static string CombinePath (params string[] paths)
|
|
{
|
|
if (paths == null)
|
|
return null;
|
|
if (paths.Length == 1)
|
|
return paths [0];
|
|
var path = Path.Combine (paths [0], paths [1]);
|
|
for (int i = 2; i < paths.Length; ++i)
|
|
path = Path.Combine (path, paths [i]);
|
|
return path;
|
|
}
|
|
|
|
private XmlDocument GetOverview (IEnumerable<string> directories)
|
|
{
|
|
var index = new XmlDocument ();
|
|
|
|
var overview = index.CreateElement ("Overview");
|
|
var assemblies= index.CreateElement ("Assemblies");
|
|
var types = index.CreateElement ("Types");
|
|
var ems = index.CreateElement ("ExtensionMethods");
|
|
|
|
index.AppendChild (overview);
|
|
overview.AppendChild (assemblies);
|
|
overview.AppendChild (types);
|
|
overview.AppendChild (ems);
|
|
|
|
bool first = true;
|
|
|
|
foreach (var dir in directories) {
|
|
var indexFile = Path.Combine (dir, "index.xml");
|
|
try {
|
|
var doc = new XmlDocument ();
|
|
doc.Load (indexFile);
|
|
if (first) {
|
|
var c = doc.SelectSingleNode ("/Overview/Copyright");
|
|
var t = doc.SelectSingleNode ("/Overview/Title");
|
|
var r = doc.SelectSingleNode ("/Overview/Remarks");
|
|
if (c != null && t != null && r != null) {
|
|
var e = index.CreateElement ("Copyright");
|
|
e.InnerXml = c.InnerXml;
|
|
overview.AppendChild (e);
|
|
|
|
e = index.CreateElement ("Title");
|
|
e.InnerXml = t.InnerXml;
|
|
overview.AppendChild (e);
|
|
|
|
e = index.CreateElement ("Remarks");
|
|
e.InnerXml = r.InnerXml;
|
|
overview.AppendChild (e);
|
|
|
|
first = false;
|
|
}
|
|
}
|
|
AddAssemblies (assemblies, doc);
|
|
AddTypes (types, doc, dir);
|
|
AddChildren (ems, doc, "/Overview/ExtensionMethods");
|
|
}
|
|
catch (Exception e) {
|
|
Message (TraceLevel.Warning, "Could not load documentation index '{0}': {1}",
|
|
indexFile, e.Message);
|
|
}
|
|
}
|
|
|
|
return index;
|
|
}
|
|
|
|
static void AddChildren (XmlNode dest, XmlDocument source, string path)
|
|
{
|
|
var n = source.SelectSingleNode (path);
|
|
if (n != null)
|
|
foreach (XmlNode c in n.ChildNodes)
|
|
dest.AppendChild (dest.OwnerDocument.ImportNode (c, true));
|
|
}
|
|
|
|
static void AddAssemblies (XmlNode dest, XmlDocument source)
|
|
{
|
|
foreach (XmlNode asm in source.SelectNodes ("/Overview/Assemblies/Assembly")) {
|
|
var n = asm.Attributes ["Name"].Value;
|
|
var v = asm.Attributes ["Version"].Value;
|
|
if (dest.SelectSingleNode (string.Format ("Assembly[@Name='{0}'][@Value='{1}']", n, v)) == null) {
|
|
dest.AppendChild (dest.OwnerDocument.ImportNode (asm, true));
|
|
}
|
|
}
|
|
}
|
|
|
|
static void AddTypes (XmlNode dest, XmlDocument source, string sourceDirectory)
|
|
{
|
|
var types = source.SelectSingleNode ("/Overview/Types");
|
|
if (types == null)
|
|
return;
|
|
foreach (XmlNode ns in types.ChildNodes) {
|
|
var n = ns.Attributes ["Name"].Value;
|
|
var nsd = dest.SelectSingleNode (string.Format ("Namespace[@Name='{0}']", n));
|
|
if (nsd == null) {
|
|
nsd = dest.OwnerDocument.CreateElement ("Namespace");
|
|
AddAttribute (nsd, "Name", n);
|
|
dest.AppendChild (nsd);
|
|
}
|
|
foreach (XmlNode t in ns.ChildNodes) {
|
|
if (!TypeInVersions (sourceDirectory, n, t))
|
|
continue;
|
|
var c = dest.OwnerDocument.ImportNode (t, true);
|
|
AddAttribute (c, "SourceDirectory", sourceDirectory);
|
|
nsd.AppendChild (c);
|
|
}
|
|
if (nsd.ChildNodes.Count == 0)
|
|
dest.RemoveChild (nsd);
|
|
}
|
|
}
|
|
|
|
static bool TypeInVersions (string sourceDirectory, string ns, XmlNode type)
|
|
{
|
|
if (opts.versions.Count == 0)
|
|
return true;
|
|
var file = Path.Combine (Path.Combine (sourceDirectory, ns), type.Attributes ["Name"].Value + ".xml");
|
|
if (!File.Exists (file))
|
|
return false;
|
|
XPathDocument doc;
|
|
using (var s = File.OpenText (file))
|
|
doc = new XPathDocument (s);
|
|
return MemberInVersions (doc.CreateNavigator ().SelectSingleNode ("/Type"));
|
|
}
|
|
|
|
static bool MemberInVersions (XPathNavigator nav)
|
|
{
|
|
return nav.Select ("AssemblyInfo/AssemblyVersion")
|
|
.Cast<object> ()
|
|
.Any (v => opts.versions.Contains (v.ToString ()));
|
|
}
|
|
|
|
static void AddAttribute (XmlNode self, string name, string value)
|
|
{
|
|
var a = self.OwnerDocument.CreateAttribute (name);
|
|
a.Value = value;
|
|
self.Attributes.Append (a);
|
|
}
|
|
|
|
private static bool DestinationIsNewer (string source, string dest)
|
|
{
|
|
return !opts.forceUpdate && File.Exists (dest) &&
|
|
File.GetLastWriteTime (source) < File.GetLastWriteTime (dest);
|
|
}
|
|
|
|
private static void PreserveMembersInVersions (XmlDocument doc)
|
|
{
|
|
if (opts.versions.Count == 0)
|
|
return;
|
|
var remove = new List<XmlNode>();
|
|
foreach (XmlNode m in doc.SelectNodes ("/Type/Members/Member")) {
|
|
if (!MemberInVersions (m.CreateNavigator ()))
|
|
remove.Add (m);
|
|
}
|
|
XmlNode members = doc.SelectSingleNode ("/Type/Members");
|
|
foreach (var m in remove)
|
|
members.RemoveChild (m);
|
|
}
|
|
}
|
|
|
|
}
|