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

…ergy.Documentation nuget package

Documentation/README.md

@@ -5,16 +5,18 @@
 To enlist public API, we use the following tool:
 
 ```csharp
+using Synergy.Documentation.Api;
+
+namespace Synergy.Documentation.Tests.Architecture.Public;
+
 [UsesVerify]
 public class Api
 {
     [Fact]
     public async Task Generate()
     {
         var assembly = typeof(ApiDescription).Assembly;
-
         var publicApi = ApiDescription.GenerateFor(assembly);
-
         await Verifier.Verify(publicApi, "md")
                       .UseMethodName("of." + assembly.GetName().Name);
     }

Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs

@@ -8,15 +8,9 @@ public class Api
     [Fact]
     public async Task Generate()
     {
-        // ARRANGE
         var assembly = typeof(ApiDescription).Assembly;
-
-        // ACT
         var publicApi = ApiDescription.GenerateFor(assembly);
-
-        // ASSERT
         await Verifier.Verify(publicApi, "md")
-                      .UseMethodName("of." + assembly.GetName()
-                                                      .Name);
+                      .UseMethodName("of." + assembly.GetName().Name);
     }
 }

Documentation/Synergy.Documentation.Tests/Docs/README.Generate.cs

@@ -5,34 +5,35 @@ namespace Synergy.Documentation.Tests.Docs;
 
 partial class README
 {
-    private static CodeFile ReadmeFile => CodeFolder.Current().Up(2).File($"{nameof(README)}.md");
+    private static readonly CodeFile readmeFile = CodeFolder.Current().Up(2).File($"{nameof(README)}.md");
+    private readonly CodeFolder architectureFolder = CodeFolder.Current().Up().Sub("Architecture");
 
     // TODO: Marcin Celej [from: Marcin Celej on: 06-01-2024]: Add here reading file path through [SourceFile] from Synergy.Documentation.Annotations
-    private static CodeFile Api => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Api.cs");
-    private Markdown.Link ApiLink => Markdown.Link.To(Api).From(ReadmeFile);
+    private CodeFile Api => this.architectureFolder.Sub("Public").File("Api.cs");
+    private Markdown.Link ApiLink => Markdown.Link.To(Api).RelativeFrom(readmeFile);
 
-    private static CodeFile ApiForSynergyDocs => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Api.of.Synergy.Documentation.verified.md");
-    private Markdown.Link ApiForSynergyDocsLink => Markdown.Link.To(ApiForSynergyDocs).From(ReadmeFile);
+    private CodeFile ApiForSynergyDocs => this.architectureFolder.Sub("Public").File("Api.of.Synergy.Documentation.verified.md");
+    private Markdown.Link ApiForSynergyDocsLink => Markdown.Link.To(ApiForSynergyDocs).RelativeFrom(readmeFile);
 
-    private static CodeFile Package => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Package.cs");
-    private Markdown.Link PackageLink => Markdown.Link.To(Package).From(ReadmeFile);
+    private CodeFile Package => this.architectureFolder.Sub("Public").File("Package.cs");
+    private Markdown.Link PackageLink => Markdown.Link.To(Package).RelativeFrom(readmeFile);
 
-    private static CodeFile Todos => CodeFolder.Current().Up().Sub("Architecture").Sub("Debt").File("Todos.cs");
-    private Markdown.Link TodosLink => Markdown.Link.To(Todos).From(ReadmeFile);
+    private CodeFile Todos => this.architectureFolder.Sub("Debt").File("Todos.cs");
+    private Markdown.Link TodosLink => Markdown.Link.To(Todos).RelativeFrom(README.readmeFile);
 
-    private static CodeFile TodosDebt => CodeFolder.Current().Up().Sub("Architecture").Sub("Debt").File("Todos.Technical.Debt.verified.md");
-    private Markdown.Link TodosDebtLink => Markdown.Link.To(TodosDebt).From(ReadmeFile);
+    private CodeFile TodosDebt => this.architectureFolder.Sub("Debt").File("Todos.Technical.Debt.verified.md");
+    private Markdown.Link TodosDebtLink => Markdown.Link.To(TodosDebt).RelativeFrom(README.readmeFile);
 
-    private static CodeFile Relations => CodeFolder.Current().Up().Sub("Architecture").Sub("Dependencies").File("Relations.cs");
-    private Markdown.Link RelationsLink => Markdown.Link.To(Relations).From(ReadmeFile);
+    private CodeFile Relations => this.architectureFolder.Sub("Dependencies").File("Relations.cs");
+    private Markdown.Link RelationsLink => Markdown.Link.To(Relations).RelativeFrom(README.readmeFile);
 
-    private static CodeFile RelationsOfMarkdown => CodeFolder.Current().Up().Sub("Architecture").Sub("Dependencies").File("Relations.of.Markdown.verified.md");
-    private Markdown.Link RelationsOfMarkdownLink => Markdown.Link.To(RelationsOfMarkdown).From(ReadmeFile);
+    private CodeFile RelationsOfMarkdown => this.architectureFolder.Sub("Dependencies").File("Relations.of.Markdown.verified.md");
+    private Markdown.Link RelationsOfMarkdownLink => Markdown.Link.To(RelationsOfMarkdown).RelativeFrom(README.readmeFile);
 
     [Fact]
     public void Generate()
     {
         var content = this.TransformText();
-        File.WriteAllText(README.ReadmeFile.FilePath, content);
+        File.WriteAllText(readmeFile.FilePath, content);
     }
 }

Documentation/Synergy.Documentation.Tests/Docs/README.cs

@@ -25,58 +25,65 @@ public partial class README : READMEBase
         /// </summary>
         public virtual string TransformText()
         {
-            this.Write("# Synergy.Documentation nuget package\r\n\r\n## Enlisting Public API\r\n\r\nTo enlist public API, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Api\r\n{\r\n    [Fact]\r\n    public async Task Generate()\r\n    {\r\n        var assembly = typeof(ApiDescription).Assembly;\r\n\r\n        var publicApi = ApiDescription.GenerateFor(assembly);\r\n\r\n        await Verifier.Verify(publicApi, \"md\")\r\n                      .UseMethodName(\"of.\" + assembly.GetName().Name);\r\n    }\r\n}\r\n```\r\n\r\nFor sample code, please check: ");
+            this.Write("# Synergy.Documentation nuget package\r\n\r\n## Enlisting Public API\r\n\r\nTo enlist public API, we use the following tool:\r\n\r\n```csharp\r\n");
 
-            #line 26 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 10 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.Api.ReadAllText()));
+
+            #line default
+            #line hidden
+            this.Write("\r\n```\r\n\r\nFor sample code, please check: ");
+
+            #line 13 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiLink));
 
             #line default
             #line hidden
             this.Write("\r\n\r\nTo see the results, please check: ");
 
-            #line 28 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 15 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiForSynergyDocsLink));
 
             #line default
             #line hidden
             this.Write("\r\n\r\n**Note:**\r\n\r\nWhen you expose your public API, you should be aware how it looks like from the outside - ");
 
-            #line 32 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 19 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiLink));
 
             #line default
             #line hidden
             this.Write(".\r\n\r\nWhen you consume some external library - you can enlist its public API and see how it looks like - ");
 
-            #line 34 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 21 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.PackageLink));
 
             #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: ");
 
-            #line 58 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 45 "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 60 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 47 "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: ");
 
-            #line 96 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 83 "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 98 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
+            #line 85 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
             this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsOfMarkdownLink));
 
             #line default

Documentation/Synergy.Documentation.Tests/Docs/README.tt

@@ -7,20 +7,7 @@
 To enlist public API, we use the following tool:
 
 ```csharp
-[UsesVerify]
-public class Api
-{
-    [Fact]
-    public async Task Generate()
-    {
-        var assembly = typeof(ApiDescription).Assembly;
-
-        var publicApi = ApiDescription.GenerateFor(assembly);
-
-        await Verifier.Verify(publicApi, "md")
-                      .UseMethodName("of." + assembly.GetName().Name);
-    }
-}
+<#= this.Api.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.ApiLink #>

Web/Sample/Synergy.Sample.Web.API.Tests/Users/Users.md

@@ -95,7 +95,7 @@ Content-Length: 129
 
 ### 2.2. Get created user pointed by "Location" header (1 request)
 
-### 2.2.2. Request to [Get user located at http://localhost/api/v1/users/275163fbe1b149e2adbddd0af5d27404]
+### 2.2.2. Request to [Get user located at http://localhost/api/v1/users/fc34987948684ac8ab5becc774173947]
 
 - Request
 ```
@@ -137,7 +137,7 @@ Content-Length: 129
 
 ### 3.1. Get user by id (1 request)
 
-### 3.1.1. Request to [Get user with id "275163fbe1b149e2adbddd0af5d27404"]
+### 3.1.1. Request to [Get user with id "fc34987948684ac8ab5becc774173947"]
 
 - Request
 ```
@@ -391,7 +391,7 @@ Content-Length: 351
 
 ### 6.1. Delete user by id (1 request)
 
-### 6.1.1. Request to [Delete user with id "275163fbe1b149e2adbddd0af5d27404"]
+### 6.1.1. Request to [Delete user with id "fc34987948684ac8ab5becc774173947"]
 
 - Request
 ```
@@ -418,7 +418,7 @@ Content-Length: 2
 
 ### 6.2. Try to get the deleted user (1 request)
 
-### 6.2.2. Request to [Get user with id "275163fbe1b149e2adbddd0af5d27404"]
+### 6.2.2. Request to [Get user with id "fc34987948684ac8ab5becc774173947"]
 
 - Request
 ```