#27: Introduced README.md automatic generation (Docs As Code) for Syn…

…ergy.Documentation nuget package
synergy-software · Jan 6, 2024 · 826e4db · 826e4db
1 parent ef709ca
commit 826e4db
Show file tree

Hide file tree

Showing 8 changed files with 45 additions and 63 deletions.
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -17,6 +17,7 @@ public class Api
     {
         var assembly = typeof(ApiDescription).Assembly;
         var publicApi = ApiDescription.GenerateFor(assembly);
+
         await Verifier.Verify(publicApi, "md")
                       .UseMethodName("of." + assembly.GetName().Name);
     }
@@ -38,15 +39,19 @@ When you consume some external library - you can enlist its public API and see h
 To manage technical debt, we use the following tool:
 
 ```csharp
+using Synergy.Documentation.Code;
+using Synergy.Documentation.Todos;
+
+namespace Synergy.Documentation.Tests.Architecture.Debt;
+
 [UsesVerify]
 public class Todos
 {
     [Fact]
     public async Task Generate()
     {
-        var rootFolder = CodeFolder.Current()
-                                   .Up(3);
-        var technicalDebt = TodoExplorer.DebtFor("Synergy.Contracts", rootFolder);
+        var rootFolder = CodeFolder.Current().Up(3);
+        var technicalDebt = TodoExplorer.DebtFor("Synergy.Documentation", rootFolder);
 
         await Verifier
               .Verify(technicalDebt, "md")
@@ -72,21 +77,21 @@ Moreover, it is much easier to spot new technical debt during the code review.
 To document dependencies of a specific class, we use the following tool:
 
 ```csharp
+using Synergy.Documentation.Api;
+using Synergy.Documentation.Markup;
+
+namespace Synergy.Documentation.Tests.Architecture.Dependencies;
+
 [UsesVerify]
 public class Relations
 {
     [Theory]
     [InlineData(typeof(Markdown))]
-    [InlineData(typeof(Markdown.Document))]
     public async Task Generate(Type type)
     {
-        // ARRANGE
-        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type);
-
-        // ACT
+        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type, includeNested: true);
         var publicApi = ApiDescription.GenerateFor(dependencies);
 
-        // ASSERT
         await Verifier.Verify(publicApi, "md")
                       .UseMethodName("of." + type.Name);
     }

diff --git a/Documentation/Synergy.Documentation.Tests/Architecture/Debt/Todos.cs b/Documentation/Synergy.Documentation.Tests/Architecture/Debt/Todos.cs
@@ -9,8 +9,7 @@ public class Todos
     [Fact]
     public async Task Generate()
     {
-        var rootFolder = CodeFolder.Current()
-                                   .Up(3);
+        var rootFolder = CodeFolder.Current().Up(3);
         var technicalDebt = TodoExplorer.DebtFor("Synergy.Documentation", rootFolder);
 
         await Verifier

diff --git a/Documentation/Synergy.Documentation.Tests/Architecture/Dependencies/Relations.cs b/Documentation/Synergy.Documentation.Tests/Architecture/Dependencies/Relations.cs
@@ -8,16 +8,12 @@ public class Relations
 {
     [Theory]
     [InlineData(typeof(Markdown))]
-    public async Task Generate(params Type[] type)
+    public async Task Generate(Type type)
     {
-        // ARRANGE
-        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type.First(), includeNested: true);
-
-        // ACT
+        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type, includeNested: true);
         var publicApi = ApiDescription.GenerateFor(dependencies);
 
-        // ASSERT
         await Verifier.Verify(publicApi, "md")
-                      .UseMethodName("of." + type.First().Name);
+                      .UseMethodName("of." + type.Name);
     }
 }
diff --git a/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs b/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs
@@ -10,6 +10,7 @@ public async Task Generate()
     {
         var assembly = typeof(ApiDescription).Assembly;
         var publicApi = ApiDescription.GenerateFor(assembly);
+
         await Verifier.Verify(publicApi, "md")
                       .UseMethodName("of." + assembly.GetName().Name);
     }

diff --git a/Documentation/Synergy.Documentation.Tests/Architecture/Public/Package.cs b/Documentation/Synergy.Documentation.Tests/Architecture/Public/Package.cs
@@ -1,6 +1,6 @@
 using Synergy.Documentation.Api;
 
-namespace Synergy.Documentation.Tests.Architecture.Dependencies;
+namespace Synergy.Documentation.Tests.Architecture.Public;
 
 [UsesVerify]
 public class Package
@@ -10,13 +10,9 @@ public class Package
     [InlineData(typeof(TheoryAttribute))]
     public async Task Generate(Type type)
     {
-        // ARRANGE
         var assembly = type.Assembly;
-
-        // ACT
         var publicApi = ApiDescription.GenerateFor(assembly, includeAssemblyVersion: true);
 
-        // ASSERT
         await Verifier.Verify(publicApi, "md")
                       .UseMethodName("of." + assembly.GetName().Name);
     }

diff --git a/Documentation/Synergy.Documentation.Tests/Docs/README.cs b/Documentation/Synergy.Documentation.Tests/Docs/README.cs
@@ -60,30 +60,44 @@ public virtual string TransformText()
 
             #line default
             #line hidden
-            this.Write(".\r\n\r\n## Managing technical debt\r\n\r\nTo manage technical debt, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Todos\r\n{\r\n    [Fact]\r\n    public async Task Generate()\r\n    {\r\n        var rootFolder = CodeFolder.Current()\r\n                                   .Up(3);\r\n        var technicalDebt = TodoExplorer.DebtFor(\"Synergy.Contracts\", rootFolder);\r\n\r\n        await Verifier\r\n              .Verify(technicalDebt, \"md\")\r\n              .UseMethodName(\"Technical.Debt\");\r\n    }\r\n}\r\n```\r\n\r\nFor sample code, please check: ");
+            this.Write(".\r\n\r\n## Managing technical debt\r\n\r\nTo manage technical debt, we use the following tool:\r\n\r\n```csharp\r\n");
 
-            #line 45 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 28 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.Todos.ReadAllText()));
+
+            #line default
+            #line hidden
+            this.Write("\r\n```\r\n\r\nFor sample code, please check: ");
+
+            #line 31 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.TodosLink));
 
             #line default
             #line hidden
             this.Write("\r\n\r\nTo see the results, please check: ");
 
-            #line 47 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 33 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.TodosDebtLink));
 
             #line default
             #line hidden
-            this.Write("\r\n\r\n**Note:** \r\n\r\nBasic idea of using this test is to have a list of all technical debt in the project.\r\nEach time developer adds a new technical debt, he should re-run this test otherwise it will fail on the CI.\r\nWhen all tech debt for the project is materialized in single file - we can start working on it.\r\nIt also helps to keep track of all tech debt in the project.\r\nMoreover, it is much easier to spot new technical debt during the code review.\r\n\r\n## Enlisting dependencies of a class\r\n\r\nTo document dependencies of a specific class, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Relations\r\n{\r\n    [Theory]\r\n    [InlineData(typeof(Markdown))]\r\n    [InlineData(typeof(Markdown.Document))]\r\n    public async Task Generate(Type type)\r\n    {\r\n        // ARRANGE\r\n        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type);\r\n\r\n        // ACT\r\n        var publicApi = ApiDescription.GenerateFor(dependencies);\r\n\r\n        // ASSERT\r\n        await Verifier.Verify(publicApi, \"md\")\r\n                      .UseMethodName(\"of.\" + type.Name);\r\n    }\r\n}\r\n```\r\n\r\nFor sample code, please check: ");
+            this.Write("\r\n\r\n**Note:** \r\n\r\nBasic idea of using this test is to have a list of all technical debt in the project.\r\nEach time developer adds a new technical debt, he should re-run this test otherwise it will fail on the CI.\r\nWhen all tech debt for the project is materialized in single file - we can start working on it.\r\nIt also helps to keep track of all tech debt in the project.\r\nMoreover, it is much easier to spot new technical debt during the code review.\r\n\r\n## Enlisting dependencies of a class\r\n\r\nTo document dependencies of a specific class, we use the following tool:\r\n\r\n```csharp\r\n");
+
+            #line 48 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.Relations.ReadAllText()));
+
+            #line default
+            #line hidden
+            this.Write("\r\n```\r\n\r\nFor sample code, please check: ");
 
-            #line 83 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 51 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsLink));
 
             #line default
             #line hidden
             this.Write("\r\n\r\nTo see the results, please check: ");
 
-            #line 85 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 53 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsOfMarkdownLink));
 
             #line default

diff --git a/Documentation/Synergy.Documentation.Tests/Docs/README.tt b/Documentation/Synergy.Documentation.Tests/Docs/README.tt
@@ -25,21 +25,7 @@ When you consume some external library - you can enlist its public API and see h
 To manage technical debt, we use the following tool:
 
 ```csharp
-[UsesVerify]
-public class Todos
-{
-    [Fact]
-    public async Task Generate()
-    {
-        var rootFolder = CodeFolder.Current()
-                                   .Up(3);
-        var technicalDebt = TodoExplorer.DebtFor("Synergy.Contracts", rootFolder);
-
-        await Verifier
-              .Verify(technicalDebt, "md")
-              .UseMethodName("Technical.Debt");
-    }
-}
+<#= this.Todos.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.TodosLink #>
@@ -59,25 +45,7 @@ Moreover, it is much easier to spot new technical debt during the code review.
 To document dependencies of a specific class, we use the following tool:
 
 ```csharp
-[UsesVerify]
-public class Relations
-{
-    [Theory]
-    [InlineData(typeof(Markdown))]
-    [InlineData(typeof(Markdown.Document))]
-    public async Task Generate(Type type)
-    {
-        // ARRANGE
-        var dependencies = Synergy.Documentation.Api.Dependencies.Of(type);
-
-        // ACT
-        var publicApi = ApiDescription.GenerateFor(dependencies);
-
-        // ASSERT
-        await Verifier.Verify(publicApi, "md")
-                      .UseMethodName("of." + type.Name);
-    }
-}
+<#= this.Relations.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.RelationsLink #>

diff --git a/Documentation/Synergy.Documentation.Tests/Synergy.Documentation.Tests.csproj b/Documentation/Synergy.Documentation.Tests/Synergy.Documentation.Tests.csproj
@@ -51,6 +51,9 @@
         <DesignTime>True</DesignTime>
         <DependentUpon>README.tt</DependentUpon>
       </Compile>
+      <Compile Update="Docs\README.Generate.cs">
+        <DependentUpon>README.tt</DependentUpon>
+      </Compile>
     </ItemGroup>
 
 </Project>