Browse Source

Build: include api docs generation in FAKE build (and include docu, for now)

provider
Christoph Ruegg 13 years ago
parent
commit
5d5ad312d8
  1. 3
      MAINTAINING.md
  2. 20
      build.fsx
  3. BIN
      tools/docu/Spark.dll
  4. BIN
      tools/docu/docu.exe
  5. 3
      tools/docu/docu.exe.config
  6. 95
      tools/docu/templates/!namespace/!type.htm.spark
  7. 1
      tools/docu/templates/!namespace/_comment.spark
  8. 12
      tools/docu/templates/!namespace/_events.spark
  9. 4
      tools/docu/templates/!namespace/_example.spark
  10. 19
      tools/docu/templates/!namespace/_fields.spark
  11. 37
      tools/docu/templates/!namespace/_methods.spark
  12. 14
      tools/docu/templates/!namespace/_namespaces.spark
  13. 24
      tools/docu/templates/!namespace/_properties.spark
  14. 3
      tools/docu/templates/!namespace/_remarks.spark
  15. 14
      tools/docu/templates/!namespace/_types.spark
  16. 3
      tools/docu/templates/!namespace/_value.spark
  17. 40
      tools/docu/templates/!namespace/index.htm.spark
  18. 4
      tools/docu/templates/_footer.spark
  19. 8
      tools/docu/templates/_namespaces.spark
  20. 10
      tools/docu/templates/_types.spark
  21. 17
      tools/docu/templates/index.htm.spark
  22. 21
      tools/docu/templates/js/example.js
  23. 19
      tools/docu/templates/js/jquery-1.3.2.min.js
  24. 11
      tools/docu/templates/js/jquery.scrollTo-min.js
  25. 11
      tools/docu/templates/js/navigation.js
  26. 233
      tools/docu/templates/main.css

3
MAINTAINING.md

@ -11,15 +11,14 @@ Repository:
- Update RELEASENOTES file with relevant changes, attributed by contributor (if external). Set date.
- Update CONTRIBUTORS file (via `git shortlog -sn`)
- Create and publish a new annotated git tag for the release, e.g. `git tag -a v2.5.0 -m "v2.5.0"`
- Consider to resync the subtree in the native provider repository.
- Consider to update the repository mirrors at codeplex, gitorious and google ([how to](http://christoph.ruegg.name/blog/2013/1/26/git-howto-mirror-a-github-repository-without-pull-refs.html)).
Publish:
- Generate manual release build from internal TeamCity
- Update release notes in NuGet packages (using package explorer)
- Create new codeplex release, attach Zip files
- Upload NuGet packages to the NuGet Gallery
- Create new Codeplex and GitHub release, attach Zip files
Misc:

20
build.fsx

@ -5,10 +5,8 @@
#I @"packages/FAKE/tools"
#r @"packages/FAKE/tools/FakeLib.dll"
open Fake
open Fake.Git
open Fake.AssemblyInfoFile
open Fake.ReleaseNotesHelper
open Fake
open Fake.DocuHelper
open System
Environment.CurrentDirectory <- __SOURCE_DIRECTORY__
@ -113,6 +111,20 @@ Target "DocsDev" (fun _ ->
==> "DocsDev"
// API REFERENCE
Target "CleanApi" (fun _ -> CleanDirs ["out" @@ "api"])
Target "Api" (fun _ ->
!! "out/lib/Net40/MathNet.Numerics.dll"
|> Docu (fun p ->
{ p with
ToolPath = "tools/docu/docu.exe"
TemplatesPath = "tools/docu/templates/"
TimeOut = TimeSpan.FromMinutes 10.
OutputPath = "out/api/" }))
// NUGET
Target "NuGet" (fun _ ->

BIN
tools/docu/Spark.dll

Binary file not shown.

BIN
tools/docu/docu.exe

Binary file not shown.

3
tools/docu/docu.exe.config

@ -0,0 +1,3 @@
<?xml version="1.0"?>
<configuration>
<startup><supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5"/></startup></configuration>

95
tools/docu/templates/!namespace/!type.htm.spark

@ -0,0 +1,95 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>${h(Type.PrettyName)} - ${WriteProductName(Assemblies[0])} Documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link type="text/css" rel="stylesheet" href="../main.css" />
<script type="text/javascript" src="../js/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="../js/jquery.scrollTo-min.js"></script>
<script type="text/javascript" src="../js/navigation.js"></script>
<script type="text/javascript" src="../js/example.js"></script>
</head>
<body>
<namespaces />
<types />
<div class="header">
<p class="class"><strong>Type</strong> ${h(Type.PrettyName)}</p>
<p><strong>Namespace</strong> ${Namespace.Name}</p>
<p if="Type.ParentType != null && Type.ParentType.PrettyName != 'object'"><strong>Parent</strong> ${Format(Type.ParentType)}</p>
<p if="Type.Interfaces.Count > 0"><strong>Interfaces</strong> ${WriteInterfaces(Type.Interfaces)}</p>
</div>
<div class="sub-header">
<if condition="(Type.Summary != null && Type.Summary.Children.Count() > 0) || (Type.Remarks != null && Type.Remarks.Children.Count() > 0)">
<div id="summary">
<comment content="Type.Summary" />
<remarks content="Type.Remarks" />
<example content="Type.Example" />
</div>
</if>
<if condition="Type.IsObsolete">
<div id="warning">
<b>Obsolete:</b> ${Type.ObsoleteReason}
</div>
</if>
<if condition="Type.Methods.Where(x => x.IsConstructor).Count() > 0">
<h3 class="section">Constructors</h3>
<ul>
<li each="var method in Type.Methods.Where(x => x.IsConstructor)">${Format(method)}</li>
</ul>
</if>
<if condition="Type.Methods.Where(x => !x.IsConstructor && x.IsStatic).Count() > 0">
<h3 class="section">Static Functions</h3>
<ul>
<li each="var method in Type.Methods.Where(x => !x.IsConstructor && x.IsStatic)">${Format(method)}</li>
</ul>
</if>
<if condition="!Type.IsStatic && Type.Methods.Where(x => !x.IsConstructor && !x.IsStatic).Count() > 0">
<h3 class="section">Methods</h3>
<ul>
<li each="var method in Type.Methods.Where(x => !x.IsConstructor && !x.IsStatic)">${Format(method)}</li>
</ul>
</if>
<if condition="Type.Events.Count > 0">
<h3 class="section">Events</h3>
<ul>
<li each="var ev in Type.Events">${Format(ev)}</li>
</ul>
</if>
<if condition="Type.Properties.Count > 0">
<h3 class="section">Properties</h3>
<ul>
<li each="var property in Type.Properties">${Format(property)}</li>
</ul>
</if>
<if condition="Type.Fields.Count > 0">
<h3 class="section">Fields</h3>
<ul>
<li each="var field in Type.Fields">${Format(field)}</li>
</ul>
</if>
</div>
<events events="Type.Events" title="'Events'" />
<var publicConstructors="Type.Methods.Where(x => x.IsPublic && x.IsConstructor)" />
<methods methods="publicConstructors" title="'Public Constructors'" />
<var publicStaticMethods="Type.Methods.Where(x => x.IsPublic && x.IsStatic)" />
<methods methods="publicStaticMethods" title="'Public Static Functions'" />
<if condition="!Type.IsStatic">
<var publicInstanceMethods="Type.Methods.Where(x => x.IsPublic && !x.IsStatic && !x.IsConstructor)" />
<methods methods="publicInstanceMethods" title="'Public Methods'" />
</if>
<properties properties="Type.Properties" title="'Public Properties'" />
<fields fields="Type.Fields" title="'Public fields'" />
<use file="../_footer" />
</body>
</html>

1
tools/docu/templates/!namespace/_comment.spark

@ -0,0 +1 @@
${Format(content)}

12
tools/docu/templates/!namespace/_events.spark

@ -0,0 +1,12 @@
<if condition="events.Count() > 0">
<h3 class="section">${title}</h3>
<div id="${ev.Name}" class="method" each="var ev in events">
<h4><strong>${h(ev.Name)}</strong></h4>
<div class="content">
<comment content="ev.Summary" />
<remarks content="ev.Remarks" />
<example content="ev.Example" />
</div>
</div>
</if>

4
tools/docu/templates/!namespace/_example.spark

@ -0,0 +1,4 @@
<div class="example" if="content != null && content.Children.Count() > 0">
<a href="javascript:void(0)">Show Example</a>
<pre>${Format(content)}</pre>
</div>

19
tools/docu/templates/!namespace/_fields.spark

@ -0,0 +1,19 @@
<if condition="fields.Count() > 0">
<h3 class="section">${title}</h3>
<div id="${field.Name}" class="method" each="var field in fields">
<h4>${h(field.ReturnType.PrettyName)} <strong>${h(field.Name)}</strong></h4>
<div class="content">
<comment content="field.Summary" />
<remarks content="field.Remarks" />
<table>
<tr>
<td>
<code>return ${Format(field.ReturnType)}</code>
</td>
</tr>
</table>
<example content="field.Example" />
</div>
</div>
</if>

37
tools/docu/templates/!namespace/_methods.spark

@ -0,0 +1,37 @@
<if condition="methods.Count() > 0">
<h3 class="section">${title}</h3>
<div id="${method.Name}" class="method" each="var method in methods">
<h4>${Format(method.ReturnType)} <strong>${h(method.PrettyName)}</strong>(${OutputMethodParams(method)})</h4>
<div class="content">
<comment content="method.Summary" />
<remarks content="method.Remarks" />
<if condition="method.IsObsolete">
<div id="warning">
<b>Obsolete:</b> ${method.ObsoleteReason}
</div>
</if>
<var hasReturn="method.ReturnType != null && method.ReturnType.PrettyName != 'void'" />
<var hasParams="method.Parameters.Any(x => x.HasDocumentation)" />
<div class="parameters" if="hasParams">
<h5>Parameters</h5>
<for each="var param in method.Parameters">
<h6><code>${Format(param.Reference)}</code> ${param.Name}</h6>
<p class="comments" if="!param.Summary.IsEmpty"><comment content="param.Summary" /></p>
</for>
</div>
<div class="return" if="!method.Returns.IsEmpty">
<h5>Return</h5>
<h6><code>${Format(method.ReturnType)}</code></h6>
<p><comment content="method.Returns" /></p>
</div>
<value content="method.Value" />
<example content="method.Example" />
</div>
</div>
</if>

14
tools/docu/templates/!namespace/_namespaces.spark

@ -0,0 +1,14 @@
<div id="namespaces">
<h2 class="fixed">Namespaces</h2>
<div class="scroll">
<ul>
<li each="var ns in Namespaces">
<if condition="ns == Namespace">
${Format(ns, class => "current")}
<else />
${Format(ns)}
</if>
</li>
</ul>
</div>
</div>

24
tools/docu/templates/!namespace/_properties.spark

@ -0,0 +1,24 @@
<if condition="properties.Count() > 0">
<h3 class="section">${title}</h3>
<div id="${property.Name}" class="method" each="var property in properties">
<h4>${Format(property.ReturnType)} <strong>${h(property.Name)}</strong> <if condition="property.HasGet">get;</if> <if condition="property.HasSet">set;</if></h4>
<div class="content">
<comment content="property.Summary" />
<remarks content="property.Remarks" />
<if condition="property.IsObsolete">
<div id="warning">
<b>Obsolete:</b> ${property.ObsoleteReason}
</div>
</if>
<div class="return" if="property.ReturnType.HasDocumentation">
<h5>Property type</h5>
<h6><code>${Format(property.ReturnType)}</code></h6>
<p><comment content="property.ReturnType.Summary" /></p>
</div>
<value content="property.Value" />
<example content="property.Example" />
</div>
</div>
</if>

3
tools/docu/templates/!namespace/_remarks.spark

@ -0,0 +1,3 @@
<blockquote class="remarks" if="content != null && content.Children.Count() > 0">
${Format(content)}
</blockquote>

14
tools/docu/templates/!namespace/_types.spark

@ -0,0 +1,14 @@
<div id="types">
<h2 class="fixed">Types in ${Namespace.PrettyName}</h2>
<div class="scroll">
<ul>
<li each="var type in Namespace.Types">
<if condition="type == Type">
${Format(type, class => "current")}
<else />
${Format(type)}
</if>
</li>
</ul>
</div>
</div>

3
tools/docu/templates/!namespace/_value.spark

@ -0,0 +1,3 @@
<blockquote class="value" if="content.Children.Count() > 0">
<strong>Value: </strong>${Format(content)}
</blockquote>

40
tools/docu/templates/!namespace/index.htm.spark

@ -0,0 +1,40 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>${Namespace.Name} - ${WriteProductName(Assemblies[0])} Documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link type="text/css" rel="stylesheet" href="../main.css" />
<script type="text/javascript" src="../js/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="../js/jquery.scrollTo-min.js"></script>
<script type="text/javascript" src="../js/navigation.js"></script>
</head>
<body>
<namespaces />
<types />
<div class="header">
<p class="class"><strong>Namespace</strong> ${Namespace.Name}</p>
</div>
<div class="sub-header">
<if condition="Namespace.HasClasses">
<h3 class="section">Classes</h3>
<ul>
<for each="var type in Namespace.Classes">
<li>${Format(type)}</li>
</for>
</ul>
</if>
<if condition="Namespace.HasInterfaces">
<h3 class="section">Interfaces</h3>
<ul>
<for each="var type in Namespace.Interfaces">
<li>${Format(type)}</li>
</for>
</ul>
</if>
<p if="!Namespace.HasTypes">This namespace is empty.</p>
</div>
<use file="../_footer" />
</body>
</html>

4
tools/docu/templates/_footer.spark

@ -0,0 +1,4 @@
<div id="footer">
<p>Based on v${WriteVersion(Assemblies[0])} of ${WriteAssemblyTitle(Assemblies[0])}</p>
<p>Generated by <a href="http://docu.jagregory.com">docu</a></p>
</div>

8
tools/docu/templates/_namespaces.spark

@ -0,0 +1,8 @@
<div id="namespaces">
<h2 class="fixed">Namespaces</h2>
<div class="scroll">
<ul>
<li each="var ns in Namespaces">${Format(ns)}</li>
</ul>
</div>
</div>

10
tools/docu/templates/_types.spark

@ -0,0 +1,10 @@
<div id="types">
<h2 class="fixed">All Types</h2>
<div class="scroll">
<ul>
<for each="var ns in Namespaces">
<li each="var type in ns.Types">${Format(type)}</li>
</for>
</ul>
</div>
</div>

17
tools/docu/templates/index.htm.spark

@ -0,0 +1,17 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>${WriteProductName(Assemblies[0])} Documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link type="text/css" rel="stylesheet" href="main.css" />
</head>
<body>
<namespaces />
<types />
<div class="header">
<p class="class">${WriteProductName(Assemblies[0])} Documentation</p>
</div>
<use file="_footer" />
</body>
</html>

21
tools/docu/templates/js/example.js

@ -0,0 +1,21 @@
$(document).ready(function() {
$('div.example').each(function(i, div) {
var a = $('a', div);
var pre = $('pre', div);
a.pre = pre;
a.preVisible = false;
pre.hide();
a.click(function() {
if (a.preVisible) {
a.pre.hide();
a.text('Show Example');
a.preVisible = false;
} else {
a.pre.show();
a.text('Hide Example');
a.preVisible = true;
}
});
});
});

19
tools/docu/templates/js/jquery-1.3.2.min.js

File diff suppressed because one or more lines are too long

11
tools/docu/templates/js/jquery.scrollTo-min.js

@ -0,0 +1,11 @@
/**
* jQuery.ScrollTo - Easy element scrolling using jQuery.
* Copyright (c) 2007-2009 Ariel Flesler - aflesler(at)gmail(dot)com | http://flesler.blogspot.com
* Dual licensed under MIT and GPL.
* Date: 5/25/2009
* @author Ariel Flesler
* @version 1.4.2
*
* http://flesler.blogspot.com/2007/10/jqueryscrollto.html
*/
;(function(d){var k=d.scrollTo=function(a,i,e){d(window).scrollTo(a,i,e)};k.defaults={axis:'xy',duration:parseFloat(d.fn.jquery)>=1.3?0:1};k.window=function(a){return d(window)._scrollable()};d.fn._scrollable=function(){return this.map(function(){var a=this,i=!a.nodeName||d.inArray(a.nodeName.toLowerCase(),['iframe','#document','html','body'])!=-1;if(!i)return a;var e=(a.contentWindow||a).document||a.ownerDocument||a;return d.browser.safari||e.compatMode=='BackCompat'?e.body:e.documentElement})};d.fn.scrollTo=function(n,j,b){if(typeof j=='object'){b=j;j=0}if(typeof b=='function')b={onAfter:b};if(n=='max')n=9e9;b=d.extend({},k.defaults,b);j=j||b.speed||b.duration;b.queue=b.queue&&b.axis.length>1;if(b.queue)j/=2;b.offset=p(b.offset);b.over=p(b.over);return this._scrollable().each(function(){var q=this,r=d(q),f=n,s,g={},u=r.is('html,body');switch(typeof f){case'number':case'string':if(/^([+-]=)?\d+(\.\d+)?(px|%)?$/.test(f)){f=p(f);break}f=d(f,this);case'object':if(f.is||f.style)s=(f=d(f)).offset()}d.each(b.axis.split(''),function(a,i){var e=i=='x'?'Left':'Top',h=e.toLowerCase(),c='scroll'+e,l=q[c],m=k.max(q,i);if(s){g[c]=s[h]+(u?0:l-r.offset()[h]);if(b.margin){g[c]-=parseInt(f.css('margin'+e))||0;g[c]-=parseInt(f.css('border'+e+'Width'))||0}g[c]+=b.offset[h]||0;if(b.over[h])g[c]+=f[i=='x'?'width':'height']()*b.over[h]}else{var o=f[h];g[c]=o.slice&&o.slice(-1)=='%'?parseFloat(o)/100*m:o}if(/^\d+$/.test(g[c]))g[c]=g[c]<=0?0:Math.min(g[c],m);if(!a&&b.queue){if(l!=g[c])t(b.onAfterFirst);delete g[c]}});t(b.onAfter);function t(a){r.animate(g,j,b.easing,a&&function(){a.call(this,n,b)})}}).end()};k.max=function(a,i){var e=i=='x'?'Width':'Height',h='scroll'+e;if(!d(a).is('html,body'))return a[h]-d(a)[e.toLowerCase()]();var c='client'+e,l=a.ownerDocument.documentElement,m=a.ownerDocument.body;return Math.max(l[h],m[h])-Math.min(l[c],m[c])};function p(a){return typeof a=='object'?a:{top:a,left:a}}})(jQuery);

11
tools/docu/templates/js/navigation.js

@ -0,0 +1,11 @@
$(document).ready(function() {
var scroll = function(selector) {
var currentItem = $(selector + ' .current');
if (currentItem)
$(selector + ' div.scroll').scrollTo(currentItem);
};
scroll('#namespaces');
scroll('#types');
});

233
tools/docu/templates/main.css

@ -0,0 +1,233 @@
body {
margin: 0;
padding: 0;
font-family: Verdana,Arial,Helvetica,sans-serif;
font-size: 90%;
}
.header {
background: #048;
border-bottom: 3px solid #006;
margin: 0;
color: #FFF;
padding: 10px;
clear: left;
font-size: 13px;
}
.header p {
margin: 0 0 4px 0;
}
.header .class {
font-size: 24px;
font-weight: bold;
}
.header strong {
font-size: 13px;
width: 100px;
float: left;
}
.header a {
background: transparent;
color: #FFF;
}
.header a:hover {
background: #FFF;
color: #039;
}
.sub-header {
margin: 0 20px;
}
.sub-header ul {
margin: 0 0 0 30px;
padding: 0;
list-style: none;
}
.sub-header ul li {
float: left;
margin: 0 15px 0 0;
padding: 0;
text-indent: 0;
}
.section {
color: #333;
border-bottom: 1px solid #999;
margin: 10px 10px 0 10px;
padding: 10px 0 0 0;
clear: left;
}
div.method {
background: #EFEFEF;
border: 1px dotted #CCC;
margin: 5px 10px 15px 10px;
padding: 0;
}
div.method h4 {
background: #CCC;
border-bottom: 1px solid #666;
color: #000;
padding: 2px 5px;
margin: 0 0 10px 0;
font-weight: normal;
}
div.method h4 a {
background: transparent;
}
div.method .content {
padding: 0 10px 5px 10px;
}
div.parameters, div.return {
background: #fff;
border: 1px solid #ccc;
padding: 10px;
margin-top: 10px;
}
div.parameters h5, div.return h5 {
color: #666;
margin: -10px 0 0 -10px;
padding: 3px;
font-weight: normal;
font-size: 10px;
border-bottom: 1px solid #ccc;
border-right: 1px solid #ccc;
float: left;
}
div.parameters h6, div.return h6 {
clear: left;
font-size: 14px;
font-weight: normal;
margin: 0;
padding: 6px 0 3px 0;
}
div.parameters p, div.return p {
border-top: 1px solid #ccc;
margin: 0;
padding: 3px 3px 0 3px;
}
#summary {
background: #EFEFEF;
border: 1px dotted #999999;
margin: 5px 10px 15px 10px;
padding: 5px 10px;
}
#namespaces {
width: 50%;
float: left;
background: #FFF;
}
#types {
width: 50%;
float: left;
background: #FFF;
margin-left: -1px;
}
#warning {
color: red ;
background: rgb(255, 218, 0);
border: 1px solid red;
margin: 20px 10px 20px 10px;
padding: 5px 10px;
}
h2.fixed {
background: #CCC;
color: #000;
border-top: 1px solid #999;
border-bottom: 1px solid #999;
margin: 0;
padding: 2px 10px;
font-size: 12px;
font-weight: bold;
}
div.scroll {
overflow: scroll;
height: 150px;
}
#namespaces ul, #types ul {
list-style: none;
margin: 0 0 10px 0;
padding: 0;
}
#namespaces ul li, #types ul li {
text-indent: 0;
padding-left: 10px;
}
a {
background: #eef;
color: #039;
text-decoration: none;
}
a:hover {
color: #FFF;
background: #039;
}
#namespaces a.current, #types a.current {
background: #039;
color: #FFF;
text-decoration: none;
}
#footer {
text-align: center;
font-size: 10px;
color: #888;
clear: left;
padding-top: 10px;
}
blockquote {
margin: 10px;
padding: 6px;
background: #F5F5F5;
border-top: 3px solid #CCC;
border-bottom: 3px solid #CCC;
}
.value {
border-top-width: 1px;
border-bottom-width: 1px;
font-size: 90%;
}
.example {
margin: 10px 0;
}
.example pre {
background: #DDD;
color: #000;
font-size: 14px;
font-family: Monaco, Consolas, Courier New, Monospace;
padding: 4px 10px;
border: 3px solid #AAA;
}
code {
font-family: Monaco, Consolas, Courier New, Monospace;
}
Loading…
Cancel
Save