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

…ergy.Documentation nuget package

Documentation/README.md

@@ -5,11 +5,13 @@
 To enlist public API, we use the following tool:
 
 ```csharp
+using Synergy.Documentation.Annotations;
 using Synergy.Documentation.Api;
 
 namespace Synergy.Documentation.Tests.Architecture.Public;
 
 [UsesVerify]
+[CodeFilePath]
 public class Api
 {
     [Fact]
@@ -39,12 +41,14 @@ 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.Annotations;
 using Synergy.Documentation.Code;
 using Synergy.Documentation.Todos;
 
 namespace Synergy.Documentation.Tests.Architecture.Debt;
 
 [UsesVerify]
+[CodeFilePath]
 public class Todos
 {
     [Fact]
@@ -77,12 +81,14 @@ 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.Annotations;
 using Synergy.Documentation.Api;
 using Synergy.Documentation.Markup;
 
 namespace Synergy.Documentation.Tests.Architecture.Dependencies;
 
 [UsesVerify]
+[CodeFilePath]
 public class Relations
 {
     [Theory]

Documentation/Synergy.Documentation.Tests/Architecture/Debt/Todos.cs

@@ -1,9 +1,11 @@
-using Synergy.Documentation.Code;
+using Synergy.Documentation.Annotations;
+using Synergy.Documentation.Code;
 using Synergy.Documentation.Todos;
 
 namespace Synergy.Documentation.Tests.Architecture.Debt;
 
 [UsesVerify]
+[CodeFilePath]
 public class Todos
 {
     [Fact]

Documentation/Synergy.Documentation.Tests/Architecture/Dependencies/Relations.cs

@@ -1,9 +1,11 @@
-using Synergy.Documentation.Api;
+using Synergy.Documentation.Annotations;
+using Synergy.Documentation.Api;
 using Synergy.Documentation.Markup;
 
 namespace Synergy.Documentation.Tests.Architecture.Dependencies;
 
 [UsesVerify]
+[CodeFilePath]
 public class Relations
 {
     [Theory]

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

@@ -1,8 +1,10 @@
-using Synergy.Documentation.Api;
+using Synergy.Documentation.Annotations;
+using Synergy.Documentation.Api;
 
 namespace Synergy.Documentation.Tests.Architecture.Public;
 
 [UsesVerify]
+[CodeFilePath]
 public class Api
 {
     [Fact]

Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.of.Synergy.Documentation.verified.md

@@ -65,6 +65,7 @@
  - CodeFile.Current(
      path: string [CallerFilePath, Optional]
    ) : CodeFile
+ - CodeFile.For<T>() : CodeFile
  - ReadAllText() : string
  - RelativeTo(
      folder: CodeFolder

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

@@ -1,8 +1,10 @@
-using Synergy.Documentation.Api;
+using Synergy.Documentation.Annotations;
+using Synergy.Documentation.Api;
 
 namespace Synergy.Documentation.Tests.Architecture.Public;
 
 [UsesVerify]
+[CodeFilePath]
 public class Package
 {
     [Theory]

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

@@ -1,5 +1,7 @@
 using Synergy.Documentation.Code;
 using Synergy.Documentation.Markup;
+using Synergy.Documentation.Tests.Architecture.Dependencies;
+using Synergy.Documentation.Tests.Architecture.Public;
 
 namespace Synergy.Documentation.Tests.Docs;
 
@@ -9,26 +11,26 @@ partial class README
     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 CodeFile Api => this.architectureFolder.Sub("Public").File("Api.cs");
-    private Markdown.Link ApiLink => Markdown.Link.To(Api).RelativeFrom(readmeFile);
+    private CodeFile ApiFile => CodeFile.For<Architecture.Public.Api>();
+    private Markdown.Link ApiLink => Markdown.Link.To(this.ApiFile).RelativeFrom(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 Markdown.Link ApiForSynergyDocsLink => Markdown.Link.To(this.ApiForSynergyDocs).RelativeFrom(readmeFile);
 
-    private CodeFile Package => this.architectureFolder.Sub("Public").File("Package.cs");
-    private Markdown.Link PackageLink => Markdown.Link.To(Package).RelativeFrom(readmeFile);
+    private CodeFile PackageFile => CodeFile.For<Package>();
+    private Markdown.Link PackageLink => Markdown.Link.To(this.PackageFile).RelativeFrom(readmeFile);
 
-    private CodeFile Todos => this.architectureFolder.Sub("Debt").File("Todos.cs");
-    private Markdown.Link TodosLink => Markdown.Link.To(Todos).RelativeFrom(README.readmeFile);
+    private CodeFile TodosFile => CodeFile.For<Architecture.Debt.Todos>();
+    private Markdown.Link TodosLink => Markdown.Link.To(this.TodosFile).RelativeFrom(README.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 Markdown.Link TodosDebtLink => Markdown.Link.To(this.TodosDebt).RelativeFrom(README.readmeFile);
 
-    private CodeFile Relations => this.architectureFolder.Sub("Dependencies").File("Relations.cs");
-    private Markdown.Link RelationsLink => Markdown.Link.To(Relations).RelativeFrom(README.readmeFile);
+    private CodeFile RelationsFile => CodeFile.For<Relations>();
+    private Markdown.Link RelationsLink => Markdown.Link.To(this.RelationsFile).RelativeFrom(README.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);
+    private Markdown.Link RelationsOfMarkdownLink => Markdown.Link.To(this.RelationsOfMarkdown).RelativeFrom(README.readmeFile);
 
     [Fact]
     public void Generate()

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

@@ -28,7 +28,7 @@ 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");
 
             #line 10 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
-            this.Write(this.ToStringHelper.ToStringWithCulture(this.Api.ReadAllText()));
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiFile.ReadAllText()));
 
             #line default
             #line hidden
@@ -63,7 +63,7 @@ public virtual string TransformText()
             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 28 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt"
-            this.Write(this.ToStringHelper.ToStringWithCulture(this.Todos.ReadAllText()));
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.TodosFile.ReadAllText()));
 
             #line default
             #line hidden
@@ -84,7 +84,7 @@ public virtual string TransformText()
             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()));
+            this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsFile.ReadAllText()));
 
             #line default
             #line hidden

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

@@ -7,7 +7,7 @@
 To enlist public API, we use the following tool:
 
 ```csharp
-<#= this.Api.ReadAllText() #>
+<#= this.ApiFile.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.ApiLink #>
@@ -25,7 +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
-<#= this.Todos.ReadAllText() #>
+<#= this.TodosFile.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.TodosLink #>
@@ -45,7 +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
-<#= this.Relations.ReadAllText() #>
+<#= this.RelationsFile.ReadAllText() #>
 ```
 
 For sample code, please check: <#= this.RelationsLink #>

Documentation/Synergy.Documentation.Tests/Synergy.Documentation.Tests.csproj

@@ -7,6 +7,14 @@
         <Nullable>enable</Nullable>
     </PropertyGroup>
 
+    <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+      <DefineConstants>TRACE;DOCUMENTATION</DefineConstants>
+    </PropertyGroup>
+
+    <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+      <DefineConstants>TRACE;DOCUMENTATION</DefineConstants>
+    </PropertyGroup>
+
     <ItemGroup>
       <None Update="Todos\Todos.Technical.Debt.verified.md">
         <ParentFile>Todos</ParentFile>
@@ -36,6 +44,7 @@
 
     <ItemGroup>
       <ProjectReference Include="..\..\Contracts\Synergy.Contracts\Synergy.Contracts.csproj" />
+      <ProjectReference Include="..\Synergy.Documentation.Annotations\Synergy.Documentation.Annotations.csproj" />
       <ProjectReference Include="..\Synergy.Documentation\Synergy.Documentation.csproj" />
     </ItemGroup>
 

Documentation/Synergy.Documentation/Code/CodeFile.cs

@@ -1,4 +1,6 @@
-using System.Runtime.CompilerServices;
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using Synergy.Documentation.Annotations;
 
 namespace Synergy.Documentation.Code;
 
@@ -7,6 +9,15 @@ public class CodeFile
     public static CodeFile Current([CallerFilePath] string path = "")
         => new(path);
 
+    public static CodeFile For<T>()
+    {
+        var attr = typeof(T).GetCustomAttribute<CodeFilePathAttribute>();
+        if (attr is null)
+            throw new InvalidOperationException($"Type {typeof(T).FullName} is not decorated with [{nameof(CodeFilePathAttribute).Replace("Attribute", "")}] attribute");
+
+        return new CodeFile(attr.FilePath);
+    }
+
     public string FilePath { get; }
     public string FileName => Path.GetFileName(FilePath);
     public string FileNameWithoutExtension => Path.GetFileNameWithoutExtension(FilePath);

Documentation/Synergy.Documentation/Synergy.Documentation.csproj

@@ -12,7 +12,7 @@
         <PackageProjectUrl>https://github.com/synergy-software/synergy.framework/tree/master/Documentation/README.md</PackageProjectUrl>
         <PackageIcon>synergy.png</PackageIcon>
         <Description>support for various docs generation</Description>
-        <Copyright>Copyright © Synergy Marcin Celej 2023</Copyright>
+        <Copyright>Copyright © Synergy Marcin Celej 2024</Copyright>
         <PackageTags>Docs As Code</PackageTags>
         <LangVersion>10</LangVersion>
         <Nullable>enable</Nullable>
@@ -47,4 +47,12 @@
       </Compile>
     </ItemGroup>
 
+    <ItemGroup>
+      <ProjectReference Include="..\Synergy.Documentation.Annotations\Synergy.Documentation.Annotations.csproj" />
+    </ItemGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\Synergy.Documentation.Annotations\Synergy.Documentation.Annotations.csproj" />
+    </ItemGroup>
+
 </Project>