Browse Source

Adding C# mdoc API reference task

Josh Engebretson 9 years ago
parent
commit
573cb16963
4 changed files with 388 additions and 2 deletions
  1. 1 1
      Build/Docs/CPlusPlus/README.md
  2. 349 0
      Build/Docs/CSharp/atomictemplate.xlst
  3. 37 0
      Build/Scripts/BuildCommon.js
  4. 1 1
      README.md

+ 1 - 1
Build/Docs/CPlusPlus/README.md

@@ -35,7 +35,7 @@ Email: [email protected]
 
 **[GitHub Wiki](https://github.com/AtomicGameEngine/AtomicGameEngine/wiki/)**
 
-**API References:** <a href="http://docs.atomicgameengine.com/api/globals.html">JavaScript/TypeScript</a>, *C# (Coming Soon)*, <a href="http://docs.atomicgameengine.com/cpp/">C++</a>
+**API References:** <a href="http://docs.atomicgameengine.com/api/modules/atomic.html">JavaScript/TypeScript</a>, <a href="http://docs.atomicgameengine.com/csharp/">C#</a>, <a href="http://docs.atomicgameengine.com/cpp/">C++</a>
 
 #### Atomic Community
 

+ 349 - 0
Build/Docs/CSharp/atomictemplate.xlst

@@ -0,0 +1,349 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <xsl:output
+    encoding="UTF-8"
+    indent="yes"
+    method="xml"
+    omit-xml-declaration="yes"
+  />
+
+  <xsl:template match="Page">
+    <html>
+      <head>
+        <title>
+          <xsl:value-of select="Title" />
+        </title>
+        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+        <xsl:call-template name="create-default-style" />
+        <xsl:call-template name="create-default-script" />
+      </head>
+      <body>
+        <!-- HEADER -->
+        <xsl:call-template name="create-default-collection-title" />
+        <xsl:call-template name="create-index" />
+        <xsl:call-template name="create-default-title" />
+        <xsl:call-template name="create-default-summary" />
+        <xsl:call-template name="create-default-signature" />
+        <xsl:call-template name="create-default-remarks" />
+        <xsl:call-template name="create-default-members" />
+        <hr size="1" />
+        <xsl:call-template name="create-default-copyright" />
+      </body>
+    </html>
+  </xsl:template>
+
+  <!-- IDENTITY TRANSFORMATION -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template name="create-default-style">
+    <style>
+      a { text-decoration: none }
+
+      div.SideBar {
+        padding-left: 1em;
+        padding-right: 1em;
+        right: 0;
+        float: right;
+        border: thin solid black;
+        background-color: #f2f2f2;
+      }
+
+      .CollectionTitle { font-weight: bold }
+      .PageTitle { font-size: 150%; font-weight: bold }
+
+      .Summary { }
+      .Signature { }
+      .Remarks { }
+      .Members { }
+      .Copyright { }
+
+      .Section { font-size: 125%; font-weight: bold }
+      p.Summary {
+        margin-left: 1em;
+      }
+      .SectionBox { margin-left: 2em }
+      .NamespaceName { font-size: 105%; font-weight: bold }
+      .NamespaceSumary { }
+      .MemberName { font-size: 115%; font-weight: bold; margin-top: 1em }
+      .Subsection { font-size: 105%; font-weight: bold }
+      .SubsectionBox { margin-left: 2em; margin-bottom: 1em }
+
+      .CodeExampleTable { background-color: #f5f5dd; border: thin solid black; padding: .25em; }
+
+      .TypesListing {
+        border-collapse: collapse;
+      }
+
+      td {
+        vertical-align: top;
+      }
+      th {
+        text-align: left;
+      }
+
+      .TypesListing td {
+        margin: 0px;
+        padding: .25em;
+        border: solid gray 1px;
+      }
+
+      .TypesListing th {
+        margin: 0px;
+        padding: .25em;
+        background-color: #f2f2f2;
+        border: solid gray 1px;
+      }
+
+      div.Footer {
+        border-top: 1px solid gray;
+        margin-top: 1.5em;
+        padding-top: 0.6em;
+        text-align: center;
+        color: gray;
+      }
+
+      span.NotEntered /* Documentation for this section has not yet been entered */ {
+        display: none;
+        font-style: italic;
+        color: red;
+      }
+
+      div.Header {
+        background: #B0C4DE;
+        border: double;
+        border-color: white;
+        border-width: 7px;
+        padding: 0.5em;
+      }
+
+      div.Header * {
+        font-size: smaller;
+      }
+
+      div.Note {
+      }
+
+      i.ParamRef {
+      }
+
+      i.subtitle {
+      }
+
+      ul.TypeMembersIndex {
+        text-align: left;
+        background: #F8F8F8;
+      }
+
+      ul.TypeMembersIndex li {
+        display: inline;
+        margin:  0.5em;
+      }
+
+      table.HeaderTable {
+      }
+
+      table.SignatureTable {
+      }
+
+      table.Documentation, table.Enumeration, table.TypeDocumentation {
+        border-collapse: collapse;
+        width: 100%;
+      }
+
+      table.Documentation tr th, table.TypeMembers tr th, table.Enumeration tr th, table.TypeDocumentation tr th {
+        background: whitesmoke;
+        padding: 0.8em;
+        border: 1px solid gray;
+        text-align: left;
+        vertical-align: bottom;
+      }
+
+      table.Documentation tr td, table.TypeMembers tr td, table.Enumeration tr td, table.TypeDocumentation tr td {
+        padding: 0.5em;
+        border: 1px solid gray;
+        text-align: left;
+        vertical-align: top;
+      }
+
+      table.TypeMembers {
+        border: 1px solid #C0C0C0;
+        width: 100%;
+      }
+
+      table.TypeMembers tr td {
+        background: #F8F8F8;
+        border: white;
+      }
+
+      table.Documentation {
+      }
+
+      table.TypeMembers {
+      }
+
+      div.CodeExample {
+        width: 100%;
+        border: 1px solid #DDDDDD;
+        background-color: #F8F8F8;
+      }
+
+      div.CodeExample p {
+        margin: 0.5em;
+        border-bottom: 1px solid #DDDDDD;
+      }
+
+      div.CodeExample div {
+        margin: 0.5em;
+      }
+
+      h4 {
+        margin-bottom: 0;
+      }
+
+      div.Signature {
+        border: 1px solid #C0C0C0;
+        background: #F2F2F2;
+        padding: 1em;
+      }
+    </style>
+  </xsl:template>
+
+  <xsl:template name="create-default-script">
+    <script type="text/JavaScript">
+      function toggle_display (block) {
+        var w = document.getElementById (block);
+        var t = document.getElementById (block + ":toggle");
+        if (w.style.display == "none") {
+          w.style.display = "block";
+          t.innerHTML = "⊟";
+        } else {
+          w.style.display = "none";
+          t.innerHTML = "⊞";
+        }
+      }
+    </script>
+  </xsl:template>
+
+  <xsl:template name="create-index">
+    <xsl:if test="
+        count(PageTitle/@id) &gt; 0 and
+        (count(Signature/@id) &gt; 0 or count(Signature/div/@id) &gt; 0) and
+        count(Remarks/@id) &gt; 0 and
+        count(Members/@id) &gt; 0
+        ">
+      <div class="SideBar">
+        <p>
+          <a>
+            <xsl:attribute name="href">
+              <xsl:text>#</xsl:text>
+              <xsl:value-of select="PageTitle/@id" />
+            </xsl:attribute>
+            <xsl:text>Overview</xsl:text>
+          </a>
+        </p>
+        <p>
+          <a>
+            <xsl:attribute name="href">
+              <xsl:text>#</xsl:text>
+              <xsl:value-of select="Signature/@id" />
+              <xsl:value-of select="Signature/div/@id" />
+            </xsl:attribute>
+            <xsl:text>Signature</xsl:text>
+          </a>
+        </p>
+        <p>
+          <a>
+            <xsl:attribute name="href">
+              <xsl:text>#</xsl:text>
+              <xsl:value-of select="Remarks/@id" />
+            </xsl:attribute>
+            <xsl:text>Remarks</xsl:text>
+          </a>
+        </p>
+        <p>
+          <a href="#Members">Members</a>
+        </p>
+        <p>
+          <a>
+            <xsl:attribute name="href">
+              <xsl:text>#</xsl:text>
+              <xsl:value-of select="Members/@id" />
+            </xsl:attribute>
+            <xsl:text>Member Details</xsl:text>
+          </a>
+        </p>
+      </div>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template name="create-default-collection-title">
+    <div class="CollectionTitle">
+      <xsl:apply-templates select="CollectionTitle/node()" />
+    </div>
+  </xsl:template>
+
+  <xsl:template name="create-default-title">
+    <h1 class="PageTitle">
+      <xsl:if test="count(PageTitle/@id) &gt; 0">
+        <xsl:attribute name="id">
+          <xsl:value-of select="PageTitle/@id" />
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates select="PageTitle/node()" />
+    </h1>
+  </xsl:template>
+
+  <xsl:template name="create-default-summary">
+    <p class="Summary">
+      <xsl:if test="count(Summary/@id) &gt; 0">
+        <xsl:attribute name="id">
+          <xsl:value-of select="Summary/@id" />
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates select="Summary/node()" />
+    </p>
+  </xsl:template>
+
+  <xsl:template name="create-default-signature">
+    <div>
+      <xsl:if test="count(Signature/@id) &gt; 0">
+        <xsl:attribute name="id">
+          <xsl:value-of select="Signature/@id" />
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates select="Signature/node()" />
+    </div>
+  </xsl:template>
+
+  <xsl:template name="create-default-remarks">
+    <div class="Remarks">
+      <xsl:if test="count(Remarks/@id) &gt; 0">
+        <xsl:attribute name="id">
+          <xsl:value-of select="Remarks/@id" />
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates select="Remarks/node()" />
+    </div>
+  </xsl:template>
+
+  <xsl:template name="create-default-members">
+    <div class="Members">
+      <xsl:if test="count(Members/@id) &gt; 0">
+        <xsl:attribute name="id">
+          <xsl:value-of select="Members/@id" />
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates select="Members/node()" />
+    </div>
+  </xsl:template>
+
+  <xsl:template name="create-default-copyright">
+    <div class="Copyright">
+      <xsl:apply-templates select="Copyright/node()" />
+    </div>
+  </xsl:template>
+</xsl:stylesheet>

+ 37 - 0
Build/Scripts/BuildCommon.js

@@ -12,6 +12,7 @@ var config = require('./BuildConfig');
 var atomicRoot = config.atomicRoot;
 var jsDocFolder = config.artifactsRoot + "Build/JSDoc/";
 var cppDocFolder = config.artifactsRoot + "Build/CPPDocs/";
+var csharpDocFolder = config.artifactsRoot + "Build/CSharpDocs/";
 
 namespace('build', function() {
 
@@ -287,6 +288,42 @@ namespace('build', function() {
 
   });
 
+  task('genmdoc', {
+    async: true
+    }, function() {
+
+    console.log( "Generating C# API Documentation..." );
+
+    // mdoc must be on path
+    var mdoc = "mdoc";
+
+    // clear destination
+    common.cleanCreateDir( csharpDocFolder );
+
+    cmds = [
+      "cd " + csharpDocFolder + " && " + mdoc + " update -o docgen -i ../../AtomicNET/Release/Desktop/AtomicNET.xml ../../AtomicNET/Release/Desktop/AtomicNET.dll",
+      "cd " + csharpDocFolder + " && " + mdoc + " export-html -o html docgen --template=../../../Build/Docs/CSharp/atomictemplate.xlst"
+    ];
+
+    jake.exec(cmds, function() {
+
+      // clear destination
+      common.cleanCreateDir( config.toolDataFolder + "Docs/CSharpDocs");
+
+      // copy into release same place as JSDocs
+      fs.copySync(csharpDocFolder, config.toolDataFolder + "Docs/CSharpDocs");
+
+      complete();
+
+      console.log( "completed installing C# API documentation" );
+
+    }, {
+
+      printStdout: true
+
+    });
+
+  });
 
   task('genexamples', {
     async: true

+ 1 - 1
README.md

@@ -39,7 +39,7 @@ If you need excellent, high performance technology which leverages the full migh
 <a href="https://github.com/AtomicGameEngine/AtomicGameEngine/wiki/">![](http://atomicgameengine.com/images/community/Community_GitHub.png)
 </a>
 
-**API References:** <a href="http://docs.atomicgameengine.com/api/globals.html" target="_blank">JavaScript/TypeScript</a>, *C# (Coming Soon)*, <a href="http://docs.atomicgameengine.com/cpp" target="_blank">C++</a>
+**API References:** <a href="http://docs.atomicgameengine.com/api/modules/atomic.html" target="_blank">JavaScript/TypeScript</a>, <a href="http://docs.atomicgameengine.com/csharp" target="_blank">C#</a>, <a href="http://docs.atomicgameengine.com/cpp" target="_blank">C++</a>
 
 #### Atomic Community