update API doc gen formatting , add a custom mesh draw example (#36)

* add a custom triangle draw example

The link to custom index / vertex buffer drawing didn't explain how to use MeshDraw

* API doc generation changes to the class pages to (a) include inherited members, (b) put all summaries at the top, and all details at the bottom, (c) clean up the formatting a little

* remove spurious settings checkin and add .vscode to .gitignore

* fix some typos in previous doc edit...   remove accidental double class description.

* Update create-a-model-from-code.md

Co-authored-by: Virgile Bello <[email protected]>

.gitignore

@@ -6,4 +6,5 @@ en/api/*.yml
 en/api/.manifest
 en/obj/
 jp_tmp/*
-build.log
+build.log
+.vscode/**

en/docfx.json

@@ -28,6 +28,7 @@
         }
       ],
       "dest": "api",
+      "filter": "filterConfig.yml",
       "properties": {
         "StrideBuildDoc": "true"
       }

en/filterConfig.yml

@@ -0,0 +1,4 @@
+apiRules:
+- exclude:
+      uidRegex: ^System\.Object
+      type: Type

en/manual/scripts/create-a-model-from-code.md

@@ -87,8 +87,37 @@ You can create models in scripts at runtime. You can do this in several differen
     model.Meshes.Add(mesh);
     ```
 
-    >[!Note]
-    >For information about how to set up vertex and index buffers, see [Drawing vertices](../graphics/low-level-api/draw-vertices.md).
+5. Here is a more complete example that draws a custom triangle..
+
+    ```cs
+    var vertices = new VertexPositionTexture[3];
+    vertices[0].Position = new Vector3(0f,0f,1f);            
+    vertices[1].Position = new Vector3(0f,1f,0f);
+    vertices[2].Position = new Vector3(0f,1f,1f);
+    var vertexBuffer = Stride.Graphics.Buffer.Vertex.New(GraphicsDevice, vertices,
+                                                         GraphicsResourceUsage.Dynamic);
+    int[] indices = { 0, 2, 1 };
+    var indexBuffer = Stride.Graphics.Buffer.Index.New(GraphicsDevice, indices);
+
+    var customMesh = new Stride.Rendering.Mesh
+    { 
+        Draw = new Stride.Rendering.MeshDraw
+        { 
+            /* Vertex buffer and index buffer setup */ 
+            PrimitiveType = Stride.Graphics.PrimitiveType.TriangleList,
+            DrawCount = indicies.Length,
+            IndexBuffer = new IndexBufferBinding(indexBuffer, true, indices.Length),
+            VertexBuffers = new[] { new VertexBufferBinding(vertexBuffer, 
+                                      VertexPositionTexture.Layout, vertexBuffer.ElementCount) },
+        }
+    };            
+    // add the mesh to the model
+    model.Meshes.Add(customMesh);
+    ```
+
+
+>[!Note]
+>For more information about how to set up vertex and index buffers, see [Drawing vertices](../graphics/low-level-api/draw-vertices.md).
 
 Finally, you need to give the model one or more materials. There are two ways to do this.
 
@@ -134,4 +163,4 @@ For example:
 
 * [Create a script](create-a-script.md)
 * [Use a script](use-a-script.md)
-* [Use prefabs](../game-studio/prefabs/use-prefabs.md)
+* [Use prefabs](../game-studio/prefabs/use-prefabs.md)

en/template/partials/class.header.tmpl.partial

@@ -1,25 +1,31 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
 
-<h1 id="{{id}}" data-uid="{{uid}}" class="stride-margin-default">{{>partials/title}}</h1>
+
+<h1 id="{{id}}" data-uid="{{uid}}" class="text-break">{{>partials/title}}</h1>
+
+{{__global.namespace}}: {{{namespace.specName.0.value}}}<br>
+{{__global.assembly}}: <tt>{{assemblies.0}}.dll</tt><br>
+
+
+<div class="markdown level0 summary">{{{summary}}}</div>
 <div class="markdown level0 conceptual">{{{conceptual}}}</div>
-<h6>
-<strong>{{__global.namespace}}</strong>: {{{namespace.specName.0.value}}} | <strong>{{__global.assembly}}</strong>: {{assemblies.0}}.dll</h6>
+
 {{#inClass}}
 <div class="inheritance">
-  <!--<h5 class='test1'>{{__global.inheritance}}</h5>-->
-{{#inheritance}}
-    <div class="level{{index}}">{{{specName.0.value}}}</div>
-{{/inheritance}}
-    <div class="level{{item.level}}"><span class="xref">{{item.name.0.value}}</span></div>
-{{#derivedClasses}}
-    <div class="level{{index}}">{{{specName.0.value}}}</div>
-{{/derivedClasses}}
+  {{#inheritance}} {{{specName.0.value}}} &rarr; {{/inheritance}} 
+  <span class="xref"><strong>{{name.0.value}}</strong></span>
+</div>
+<div class="derivedClasses">
+   Derived from {{name.0.value}}: {{#derivedClasses}} {{{specName.0.value}}} {{/derivedClasses}}
 </div>
 {{/inClass}}
-<div class="markdown level0 summary">{{{summary}}}</div>
+
+<p>
+
 <div class="codewrapper">
   <pre><code class="lang-{{_lang}} hljs">{{syntax.content.0.value}}</code></pre>
 </div>
+
 {{#syntax.parameters.0}}
 <h5 class="parameters">{{__global.parameters}}</h5>
 <table class="table table-bordered table-striped table-condensed">
@@ -90,4 +96,4 @@
 {{/example.0}}
 {{#example}}
 {{{.}}}
-{{/example}}
+{{/example}}

en/template/partials/class.sectionDetailed.tmpl.partial

@@ -0,0 +1,183 @@
+
+{{#children}}
+
+<hr>
+
+{{#overload}}
+<a id="{{id}}" data-uid="{{uid}}"></a>
+{{/overload}}
+
+<h4 id="{{id}}" data-uid="{{uid}}">{{name.0.value}}</h4>
+
+<div class="markdown level1 summary">{{{summary}}}</div>
+<div class="markdown level1 conceptual">{{{conceptual}}}</div>
+
+{{#syntax}}
+<div class="codewrapper">
+  <pre><code class="lang-{{_lang}} hljs">{{syntax.content.0.value}}</code></pre>
+</div>
+
+{{#parameters.0}}
+<h5 class="parameters">{{__global.parameters}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/parameters.0}}
+{{#parameters}}
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td><span class="parametername">{{{id}}}</span></td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/parameters}}
+{{#parameters.0}}
+  </tbody>
+</table>
+{{/parameters.0}}
+{{#return}}
+<h5 class="returns">{{__global.returns}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/return}}
+{{#typeParameters.0}}
+<h5 class="typeParameters">{{__global.typeParameters}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/typeParameters.0}}
+{{#typeParameters}}
+    <tr>
+      <td><span class="parametername">{{{id}}}</span></td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/typeParameters}}
+{{#typeParameters.0}}
+  </tbody>
+</table>
+{{/typeParameters.0}}
+{{#fieldValue}}
+<h5 class="fieldValue">{{__global.fieldValue}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/fieldValue}}
+{{#propertyValue}}
+<h5 class="propertyValue">{{__global.propertyValue}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/propertyValue}}
+{{#eventType}}
+<h5 class="eventType">{{__global.eventType}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/eventType}}
+{{/syntax}}
+{{#overridden}}
+<h5 class="overrides">{{__global.overrides}}</h5>
+<div><xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
+{{/overridden}}
+{{#remarks}}
+<h5 id="{{id}}_remarks">{{__global.remarks}}</h5>
+<div class="markdown level1 remarks">{{{remarks}}}</div>
+{{/remarks}}
+{{#example.0}}
+<h5 id="{{id}}_examples">{{__global.examples}}</h5>
+{{/example.0}}
+{{#example}}
+{{{.}}}
+{{/example}}
+{{#exceptions.0}}
+<h5 class="exceptions">{{__global.exceptions}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.condition}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/exceptions.0}}
+{{#exceptions}}
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/exceptions}}
+{{#exceptions.0}}
+  </tbody>
+</table>
+{{/exceptions.0}}
+{{#seealso.0}}
+<h5 id="{{id}}_seealso">{{__global.seealso}}</h5>
+<div class="seealso">
+{{/seealso.0}}
+{{#seealso}}
+  {{#isCref}}
+    <div>{{{type.specName.0.value}}}</div>
+  {{/isCref}}
+  {{^isCref}}
+    <div>{{{url}}}</div>
+  {{/isCref}}
+{{/seealso}}
+{{#seealso.0}}
+</div>
+{{/seealso.0}}
+{{/children}}

en/template/partials/class.sectionSummary.tmpl.partial

@@ -0,0 +1,41 @@
+
+{{!
+   ---------------------------
+
+   This displays the summary table of class constructors, properties, methods, etc..
+
+   ---------------------------
+
+}}
+
+
+{{#children.0}}  
+  <table class="table table-bordered table-condensed">
+    <thead><tr>
+      <th colspan="2">{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+      </tr>
+    </thead>      
+    <tbody>
+{{/children.0}}
+        
+    {{#children}}       {{!  ----- this includes Properties, Methods, etc -----  }}
+
+        <tr><th align="center" colspan="3" id="{{id}}">{{>partials/classSubtitle}}</th></tr>
+
+        {{#children}}
+            <tr>
+            <Td class="stride-icon-column">
+                <span class="stride-{{type}}-icon"></span>
+            </td>
+            <td><a href="#{{id}}">{{name.0.value}}<a></td>
+            <td>{{{summary}}}</td>
+            </tr>
+        {{/children}}
+
+    {{/children}}
+
+{{#children.0}}  
+  </tbody> <!-- end tbody --> 
+  </table>  
+{{/children.0}}

en/template/partials/class.tmpl.partial

@@ -1,152 +1,81 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
 
 {{>partials/class.header}}
-{{#children}}
-<div class="stride-{{id}}-wrapper">
-<h2 id="{{id}}">{{>partials/classSubtitle}}</h2>
-<table class="table table-bordered table-striped table-condensed">
-  <thead>
-    <tr>
-      <th colspan="2">{{__global.name}}</th>
-      <th>{{__global.description}}</th>
-    </tr>
-  </thead>
-  <tbody>
-{{#children}}
-    <tr>
-      <td class="stride-icon-column">
-        <span class="stride-{{type}}-icon"></span>
-      </td>
-      <td><a href="#{{id}}">{{name.0.value}}</a></td>
-      <td>{{{summary}}}</td>
-    </tr>
+
+{{>partials/class.sectionSummary}}  
+
+{{#children}}       {{!  ----- this includes Properties, Methods, etc -----  }}
+
+  {{^_disableContribution}}
+  {{#docurl}}
+  <span class="small pull-right mobile-hide">
+    <span class="divider">|</span>
+    <a href="{{docurl}}">{{__global.improveThisDoc}}</a>
+  </span>{{/docurl}}
+  {{#sourceurl}}
+  <span class="small pull-right mobile-hide">
+    <a href="{{sourceurl}}">{{__global.viewSource}}</a>
+  </span>{{/sourceurl}}
+  {{/_disableContribution}}
+
+
+  <h3 id="{{id}}">{{>partials/classSubtitle}}</h3>
+  {{>partials/class.sectionDetailed}}  
 {{/children}}
-  </tbody>
-</table>
-{{#children}}
-{{^_disableContribution}}
-{{#sourceurl}}
-<span class="small pull-right mobile-hide">
-  <a href="{{sourceurl}}">{{__global.viewSource}}</a>
-</span>{{/sourceurl}}
-{{/_disableContribution}}
-<h3 id="{{id}}" data-uid="{{uid}}" class="stride-bordered-title">{{name.0.value}}</h3>
-<div class="markdown level1 summary">{{{summary}}}</div>
-<div class="markdown level1 conceptual">{{{conceptual}}}</div>
-{{#syntax}}
-<div class="codewrapper">
-  <pre><code class="lang-{{_lang}} hljs">{{syntax.content.0.value}}</code></pre>
-</div>
-<div class="stride-{{type}}">
-{{#fieldValue}}
-<div class="stride-fieldValue">
-  <i>Type: </i>{{{type.specName.0.value}}}
-  <p>{{{description}}}</p>
-</div>
-{{/fieldValue}}
-{{#propertyValue}}
-<div class="stride-propertyValue">
-  <i>Type: </i>{{{type.specName.0.value}}}
-  <p>{{{description}}}</p>
-</div>
-{{/propertyValue}}
+
+<hr> 
+
+<!------ inherited members --------> 
+
+{{#inheritedMembers.0}}
+<h3 id="inheritedMembers_header">{{__global.inheritedMembers}}</h3>
+<div class="inheritedMembers">
+{{/inheritedMembers.0}}
+{{#inheritedMembers}}
+  <div>
+  {{#definition}}
+    <xref uid="{{definition}}" text="{{nameWithType.0.value}}" alt="{{fullName.0.value}}"/>
+  {{/definition}}
+  {{^definition}}
+    <xref uid="{{uid}}" text="{{nameWithType.0.value}}" alt="{{fullName.0.value}}"/>
+  {{/definition}}
+  </div>
+{{/inheritedMembers}}
+{{#inheritedMembers.0}}
 </div>
-{{#remarks}}
-<div class="markdown level1 remarks">{{{remarks}}}</div>
-{{/remarks}}
-{{#parameters.0}}
-<h4 class="parameters">{{__global.parameters}}</h4>
-<table class="table table-bordered table-striped table-condensed">
-  <thead>
-    <tr>
-      <th>{{__global.type}}</th>
-      <th>{{__global.name}}</th>
-      <th>{{__global.description}}</th>
-    </tr>
-  </thead>
-  <tbody>
-{{/parameters.0}}
-{{#parameters}}
-    <tr>
-      <td>{{{type.specName.0.value}}}</td>
-      <td><em>{{{id}}}</em></td>
-      <td>{{{description}}}</td>
-    </tr>
-{{/parameters}}
-{{#parameters.0}}
-  </tbody>
-</table>
-{{/parameters.0}}
-{{#syntax.return}}
-<h4 class="returns">{{__global.returns}}</h4>
-<div class="stride-returns">
-  <i>Type: </i>{{{type.specName.0.value}}}
-  <p>{{{description}}}</p>
+{{/inheritedMembers.0}}
+
+
+
+{{#extensionMethods.0}}
+<h3 id="extensionmethods">{{__global.extensionMethods}}</h3>
+{{/extensionMethods.0}}
+{{#extensionMethods}}
+<div>
+  {{#definition}}
+    <xref uid="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
+  {{^definition}}
+    <xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
 </div>
-{{/syntax.return}}
-{{#syntax.typeParameters.0}}
-<h4 class="typeParameters">{{__global.typeParameters}}</h4>
-<table class="table table-bordered table-striped table-condensed">
-  <thead>
-    <tr>
-      <th>{{__global.name}}</th>
-      <th>{{__global.description}}</th>
-    </tr>
-  </thead>
-  <tbody>
-{{/syntax.typeParameters.0}}
-{{#syntax.typeParameters}}
-    <tr>
-      <td><em>{{{id}}}</em></td>
-      <td>{{{description}}}</td>
-    </tr>
-{{/syntax.typeParameters}}
-{{#syntax.typeParameters.0}}
-  </tbody>
-</table>
-{{/syntax.typeParameters.0}}
-{{#eventType}}
-<h5 class="eventType stride-hidden-table">{{__global.eventType}}</h5>
-<table class="table table-bordered table-striped table-condensed stride-hidden-table">
-  <thead>
-    <tr>
-      <th colspan="2">{{__global.type}}</th>
-      <th>{{__global.description}}</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td class="stride-icon-column">
-        <span class="stride-events-icon"></span>
-      </td>
-      <td>{{{type.specName.0.value}}}</td>
-      <td>{{{description}}}</td>
-    </tr>
-  </tbody>
-</table>
-{{/eventType}}
-{{/syntax}}
-{{#exceptions.0}}
-<h4 class="exceptions">{{__global.exceptions}}</h4>
-<table class="table table-bordered table-striped table-condensed">
-  <thead>
-    <tr>
-      <th>{{__global.type}}</th>
-      <th>{{__global.condition}}</th>
-    </tr>
-  </thead>
-  <tbody>
-{{/exceptions.0}}
-{{#exceptions}}
-    <tr>
-      <td>{{{type.specName.0.value}}}</td>
-      <td>{{{description}}}</td>
-    </tr>
-{{/exceptions}}
-{{#exceptions.0}}
-  </tbody>
-</table>
-{{/exceptions.0}}
-{{/children}}
+{{/extensionMethods}}
+
+
+
+
+{{#seealso.0}}
+<h3 id="seealso">{{__global.seealso}}</h3>
+<div class="seealso">
+{{/seealso.0}}
+{{#seealso}}
+  {{#isCref}}
+    <div>{{{type.specName.0.value}}}</div>
+  {{/isCref}}
+  {{^isCref}}
+    <div>{{{url}}}</div>
+  {{/isCref}}
+{{/seealso}}
+{{#seealso.0}}
 </div>
-{{/children}}
+{{/seealso.0}}

en/template/partials/title.tmpl.partial

@@ -0,0 +1,49 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{#inPackage}}
+{{name.0.value}} Package 
+{{/inPackage}}
+{{#inNamespace}}
+{{name.0.value}} Namespace 
+{{/inNamespace}}
+{{#inClass}}
+{{name.0.value}} Class
+{{/inClass}}
+{{#inStruct}}
+{{name.0.value}} Struct 
+{{/inStruct}}
+{{#inInterface}}
+{{name.0.value}} Interface 
+{{/inInterface}}
+{{#inEnum}}
+{{name.0.value}} Enum 
+{{/inEnum}}
+{{#inDelegate}}
+{{name.0.value}} Delegate 
+{{/inDelegate}}
+{{#inConstructor}}
+{{name.0.value}} Constructor 
+{{/inConstructor}}
+{{#inField}}
+{{name.0.value}} Field 
+{{/inField}}
+{{#inProperty}}
+{{name.0.value}} Property 
+{{/inProperty}}
+{{#inMethod}}
+{{name.0.value}} Method 
+{{/inMethod}}
+{{#inEvent}}
+{{name.0.value}} Event 
+{{/inEvent}}
+{{#inOperator}}
+{{name.0.value}} Operator 
+{{/inOperator}}
+{{#inEii}}
+{{name.0.value}} Explict Interface Implementation 
+{{/inEii}}
+{{#inVariable}}
+{{name.0.value}} Variable 
+{{/inVariable}}
+{{#inTypeAlias}}
+{{name.0.value}} Type Alias 
+{{/inTypeAlias}}