Add support for DocFx doc generation to dotnet codegen (#557)

ZimmerA · mr-c · web-flow · commit 9f5180b913ad · 2022-06-24T21:55:58.000+02:00
* Add support for DocFx doc generation to dotnet codegen

* Fix CI

* Update schema_salad/dotnet_codegen.py

Co-authored-by: Michael R. Crusoe &lt;1330696+mr-c@users.noreply.github.com&gt;

* Fix error in pd string

Co-authored-by: Michael R. Crusoe &lt;1330696+mr-c@users.noreply.github.com&gt;
diff --git a/schema_salad/dotnet/DocFx/filterConfig.yml b/schema_salad/dotnet/DocFx/filterConfig.yml
@@ -0,0 +1,17 @@
+apiRules:
+- exclude:
+    # inherited members from Form
+    uidRegex: ^System\.Windows\.Forms\.Form\..*$
+    type: Member
+- exclude:
+    # inherited members from Control
+    uidRegex: ^System\.Windows\.Forms\.Control\..*$
+    type: Member	
+- exclude:
+    # mentioning types from System.* namespace
+    uidRegex: ^System\..*$
+    type: Type	
+- exclude:
+    # mentioning types from Microsoft.* namespace
+    uidRegex: ^Microsoft\..*$
+    type: Type
diff --git a/schema_salad/dotnet/DocFx/index.md b/schema_salad/dotnet/DocFx/index.md
@@ -0,0 +1 @@
+${project_description}
diff --git a/schema_salad/dotnet/DocFx/toc.yml b/schema_salad/dotnet/DocFx/toc.yml
@@ -0,0 +1,4 @@
+- name: Home
+  href: index.md
+- name: API-Reference
+  href: reference/
diff --git a/schema_salad/dotnet/Project.csproj.template b/schema_salad/dotnet/Project.csproj.template
@@ -6,9 +6,17 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <EnablePreviewFeatures>True</EnablePreviewFeatures>
+    <PackageId>${project_name}</PackageId>
+    <Version>0.1.0</Version>
+    <Authors></Authors>
+    <BuildDocFx Condition=" '$(Configuration)'=='Debug' ">false</BuildDocFx>
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="docfx.console" Version="2.59.2">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.CodeStyle" Version="4.2.0">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
diff --git a/schema_salad/dotnet/README.md b/schema_salad/dotnet/README.md
@@ -0,0 +1,2 @@
+# ${project_name}
+${project_description}
diff --git a/schema_salad/dotnet/Test.csproj.template b/schema_salad/dotnet/Test.csproj.template
diff --git a/schema_salad/dotnet/docfx.json b/schema_salad/dotnet/docfx.json
@@ -0,0 +1,58 @@
+{
+    "metadata": [
+        {
+            "src": [
+                {
+                    "files": [
+                        "*.csproj"
+                    ],
+                    "src": "./"
+                }
+            ],
+            "dest": "../DocFx/reference",
+            "disableGitFeatures": false,
+            "disableDefaultFilter": false,
+            "filter": "../DocFx/filterConfig.yml"
+        }
+    ],
+    "build": {
+        "content": [
+            {
+                "files": [
+                    "reference/**.yml",
+                    "reference/index.md"
+                ],
+                "src": "../DocFx"
+            },
+            {
+                "files": [
+                    "*.md",
+                    "toc.yml"
+                ],
+                "src": "../DocFx"
+            }
+        ],
+        "resource": [
+            {
+                "files": [
+                    "images/**"
+                ],
+                "src": "../DocFx"
+            }
+        ],
+        "dest": "../docs",
+        "globalMetadataFiles": [],
+        "fileMetadataFiles": [],
+        "postProcessors": [],
+        "markdownEngineName": "markdig",
+        "noLangKeyword": false,
+        "keepFileLink": false,
+        "cleanupCacheHistory": false,
+        "disableGitFeatures": false,
+        "globalMetadata": {
+            "_appTitle": "Documentation",
+            "_enableSearch": true,
+            "_disableContribution": true
+        }
+    }
+}
diff --git a/schema_salad/dotnet/gitignore b/schema_salad/dotnet/gitignore
@@ -395,4 +395,8 @@ FodyWeavers.xsd
 *.msp
 
 # JetBrains Rider
-*.sln.iml
+*.sln.iml
+
+# DocFx
+DocFx/
+CWLDotNet/log.txt
diff --git a/schema_salad/dotnet/util/Loaders/RootLoader.cs b/schema_salad/dotnet/util/Loaders/RootLoader.cs
@@ -5,7 +5,7 @@ namespace ${project_name};
 
 public class RootLoader
 {
-    public static ${root_loader_type} LoadDocument(in Dictionary<object, object> doc, in string baseUri_, in LoadingOptions? loadingOptions_ = null)
+    public static ${root_loader_type} LoadDocument(Dictionary<object, object> doc, string baseUri_, LoadingOptions? loadingOptions_ = null)
     {
         string baseUri = EnsureBaseUri(baseUri_);
         LoadingOptions loadingOptions;
@@ -23,7 +23,7 @@ public class RootLoader
         return outDoc;
     }
 
-    public static ${root_loader_type} LoadDocument(in string doc, in string uri_, in LoadingOptions? loadingOptions_ = null)
+    public static ${root_loader_type} LoadDocument(string doc, string uri_, LoadingOptions? loadingOptions_ = null)
     {
         string uri = EnsureBaseUri(uri_);
         LoadingOptions loadingOptions;
diff --git a/schema_salad/dotnet/util/Utilities.cs b/schema_salad/dotnet/util/Utilities.cs
@@ -26,7 +26,7 @@ public static string Shortname(string inputId)
         }
     }
 
-    public static UriBuilder Split(string uri)
+    internal static UriBuilder Split(string uri)
     {
         Uri splitUri = new(uri, UriKind.RelativeOrAbsolute);
         UriBuilder split;
diff --git a/schema_salad/dotnet_codegen.py b/schema_salad/dotnet_codegen.py
@@ -16,6 +16,7 @@
 )
 
 import pkg_resources
+from xml.sax.saxutils import escape
 
 from . import _logger, schema
 from .codegen_base import CodeGenBase, TypeDef
@@ -28,7 +29,7 @@ def doc_to_doc_string(doc: Optional[str], indent_level: int = 0) -> str:
     """Generate a documentation string from a schema salad doc field."""
     lead = "" + "    " * indent_level + "/// "
     if doc:
-        doc_str = "\n".join([f"{lead}{line}" for line in doc.split("\n")])
+        doc_str = "\n".join([f"{lead}{escape(line)}" for line in doc.split("\n")])
     else:
         doc_str = ""
     return doc_str
@@ -858,9 +859,9 @@ def typedsl_loader(self, inner: TypeDef, ref_scope: Optional[int]) -> TypeDef:
 
     def epilogue(self, root_loader: TypeDef) -> None:
         """Trigger to generate the epilouge code."""
-        pd = "This project contains DotNet objects and utilities "
-        pd = pd + ' auto-generated by <a href=\\"https://github.com/'
-        pd = pd + 'common-workflow-language/schema_salad\\">Schema Salad</a>'
+        pd = "This project contains .Net objects and utilities "
+        pd = pd + ' auto-generated by <a href="https://github.com/'
+        pd = pd + 'common-workflow-language/schema_salad">Schema Salad</a>'
         pd = pd + " for parsing documents corresponding to the "
         pd = pd + str(self.base_uri) + " schema."
 
@@ -884,13 +885,22 @@ def expand_resource_template_to(resource: str, path: Path) -> None:
             _ensure_directory_and_write(path, src)
 
         expand_resource_template_to("editorconfig", self.target_dir / ".editorconfig")
-        expand_resource_template_to(".gitignore", self.target_dir / ".gitignore")
+        expand_resource_template_to("gitignore", self.target_dir / ".gitignore")
         expand_resource_template_to("LICENSE", self.target_dir / "LICENSE")
+        expand_resource_template_to("README.md", self.target_dir / "README.md")
         expand_resource_template_to("Solution.sln", self.target_dir / "Solution.sln")
         expand_resource_template_to(
-            "Project.csproj",
+            "Project.csproj.template",
             self.target_dir / self.package / Path(self.package + ".csproj"),
         )
+        expand_resource_template_to(
+            "Test.csproj.template",
+            self.test_src_dir / "Test.csproj",
+        )
+        expand_resource_template_to(
+            "docfx.json",
+            self.target_dir / self.package / "docfx.json",
+        )
         expand_resource_template_to(
             "AssemblyInfo.cs",
             self.target_dir / self.package / "Properties" / "AssemblyInfo.cs",
@@ -941,9 +951,14 @@ def expand_resource_template_to(resource: str, path: Path) -> None:
             root_loader=root_loader.name,
             root_loader_type=root_loader.instance_type or "object",
             tests=example_tests,
+            project_description=pd,
         )
 
-        util_src_dirs = {"util": self.main_src_dir / "util", "Test": self.test_src_dir}
+        util_src_dirs = {
+            "util": self.main_src_dir / "util",
+            "Test": self.test_src_dir,
+            "DocFx": self.target_dir / "DocFx",
+        }
 
         def copy_utils_recursive(util_src: str, util_target: Path) -> None:
             for util in pkg_resources.resource_listdir(__name__, f"dotnet/{util_src}"):

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# ${project_name}`
	`2`	`+${project_description}`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ namespace ${project_name};`
`5`	`5`
`6`	`6`	`public class RootLoader`
`7`	`7`	`{`
`8`		`- public static ${root_loader_type} LoadDocument(in Dictionary<object, object> doc, in string baseUri_, in LoadingOptions? loadingOptions_ = null)`
	`8`	`+ public static ${root_loader_type} LoadDocument(Dictionary<object, object> doc, string baseUri_, LoadingOptions? loadingOptions_ = null)`
`9`	`9`	`{`
`10`	`10`	`string baseUri = EnsureBaseUri(baseUri_);`
`11`	`11`	`LoadingOptions loadingOptions;`
`@@ -23,7 +23,7 @@ public class RootLoader`
`23`	`23`	`return outDoc;`
`24`	`24`	`}`
`25`	`25`
`26`		`- public static ${root_loader_type} LoadDocument(in string doc, in string uri_, in LoadingOptions? loadingOptions_ = null)`
	`26`	`+ public static ${root_loader_type} LoadDocument(string doc, string uri_, LoadingOptions? loadingOptions_ = null)`
`27`	`27`	`{`
`28`	`28`	`string uri = EnsureBaseUri(uri_);`
`29`	`29`	`LoadingOptions loadingOptions;`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ public static string Shortname(string inputId)`
`26`	`26`	`}`
`27`	`27`	`}`
`28`	`28`
`29`		`- public static UriBuilder Split(string uri)`
	`29`	`+ internal static UriBuilder Split(string uri)`
`30`	`30`	`{`
`31`	`31`	`Uri splitUri = new(uri, UriKind.RelativeOrAbsolute);`
`32`	`32`	`UriBuilder split;`