devlooped · kzu · Jan 6, 2023 · Jan 6, 2023
diff --git a/img/ThisAssembly.Resources.png b/img/ThisAssembly.Resources.png
diff --git a/img/ThisAssembly.Resources2.png b/img/ThisAssembly.Resources2.png
diff --git a/readme.md b/readme.md
@@ -3,8 +3,8 @@
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.svg?color=green)](https://www.nuget.org/packages/ThisAssembly)
-[![License](https://img.shields.io/github/license/kzu/ThisAssembly.svg?color=blue)](https://github.com//kzu/ThisAssembly/blob/main/LICENSE)
-[![Build](https://github.com/kzu/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/kzu/ThisAssembly/actions)
+[![License](https://img.shields.io/github/license/devlooped/ThisAssembly.svg?color=blue)](https://github.com//devlooped/ThisAssembly/blob/main/LICENSE)
+[![Build](https://github.com/devlooped/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/devlooped/ThisAssembly/actions)
 
 
 Exposes project and assembly level information as constants in the ThisAssembly 
@@ -13,106 +13,41 @@ class using source generators powered by Roslyn.
 The main generated entry point type is `ThisAssembly` in the global namespace, 
 and is declared as partial so you can extend it too with manually created members.
 
-Each package in turn extends this partial class too to add their own constants.
+Each package in turn extends this partial class to add their own nestes types 
+and members.
 
 The [ThisAssembly](https://nuget.org/packages/ThisAssembly) meta-package includes 
 all the other packages for convenience.
 
-> NOTE: as of .NET 5.0, only C# is supported for source generators.
+> NOTE: for now, ThisAssembly only generates C# code.
 
 ## ThisAssembly.AssemblyInfo
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.AssemblyInfo.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.AssemblyInfo.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
 
-This package generates a static `ThisAssembly.Info` class with public 
-constants exposing the following attribute values generated by default for SDK style projects:
-
-* AssemblyConfigurationAttribute
-* AssemblyCompanyAttribute
-* AssemblyTitleAttribute
-* AssemblyDescriptionAttribute
-* AssemblyProductAttribute
-* AssemblyCopyrightAttribute
-
-* AssemblyVersionAttribute
-* AssemblyInformationalVersionAttribute
-* AssemblyFileVersionAttribute
-
-If your project includes these attributes by other means, they will still be emitted properly 
-on the `ThisAssembly.Info` class.
-
-![](img/ThisAssembly.AssemblyInfo.png)
+<!-- include src/ThisAssembly.AssemblyInfo/readme.md#content -->
 
 ## ThisAssembly.Constants
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Constants.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Constants)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Constants.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Constants)
 
-This package generates a static `ThisAssembly.Constants` class with public
-constants for `@(Constant)` MSBuild items in the project.
-
-![](img/ThisAssembly.Constants.png)
-
-In addition to arbitrary constants via `<Constant ...>`, it's quite useful in particular in test projects, to generate constants for files in the project, so there's also a shorthand for those:
-
-```xml
-  <ItemGroup>
-    <FileConstant Include="@(Content)" />
-  </ItemGroup>
-```
-
-Which results in:
-
-![](img/ThisAssembly.Constants2.png)
-
+<!-- include src/ThisAssembly.Constants/readme.md#content -->
 
 ## ThisAssembly.Metadata
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Metadata.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Metadata)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Metadata.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Metadata)
 
-This package provides a static `ThisAssembly.Metadata` class with public 
-constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for 
-the project.
-
-![](img/ThisAssembly.Metadata.png)
-
-For an attribute declared (i.e. in *AssemblyInfo.cs*) like:
-
-```csharp
-  [assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")]
-```
-
-A corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided. 
-The metadata attribute can alternatively be declared using MSBuild syntax in the project 
-(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items):
-
-```xml
-    <ItemGroup>
-      <AssemblyMetadata Include="Foo" Value="Bar" />
-    </ItemGroup>
-```
+<!-- include src/ThisAssembly.Metadata/readme.md#content -->
 
 ## ThisAssembly.Project
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Project.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Project)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Project.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Project)
 
-This package generates a static `ThisAssembly.Project` class with public 
-constants exposing project properties that have been opted into this mechanism by adding 
-them as `ProjectProperty` MSBuild items in project file, such as:
-
-```xml
-  <PropertyGroup>
-    <Foo>Bar</Foo>
-  </PropertyGroup>
-  <ItemGroup>
-    <ProjectProperty Include="Foo" />
-  </ItemGroup>
-```
-
-![](img/ThisAssembly.Project.png)
+<!-- include src/ThisAssembly.Project/readme.md#content -->
 
 ## ThisAssembly.Resources
 
@@ -122,82 +57,19 @@ them as `ProjectProperty` MSBuild items in project file, such as:
 This package generates a static `ThisAssembly.Resources` class with public 
 properties exposing shortcuts to retrieve the contents of embedded resources.
 
-
-```xml
-  <ItemGroup>
-    <EmbeddedResource Include="Content/Docs/License.md" />
-  </ItemGroup>
-```
-
-![](img/ThisAssembly.Resources.png)
+<!-- include src/ThisAssembly.Resources/readme.md#content -->
 
 ## ThisAssembly.Strings
 
 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Strings.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Strings)
 [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Strings.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Strings)
 
-![](img/ThisAssembly.Strings.gif)
-
-This package generates a static `ThisAssembly.Strings` class with public 
-constants exposing string resources in .resx files or methods with the right number of 
-parameters for strings that use formatting parameters. 
-
-In addition, it groups constants and methods in nested classes according to an optional 
-underscore separator to organize strings. For example, *User_InvalidCredentials* can be
-accessed with *ThisAssembly.Strings.User.InvalidCredentials* if it contains a simple string, 
-or as a method with the right number of parametres if its value has a format string.
-
-Given the following Resx file:
-
-| Name                          | Value                                 | Comment           |
-|-------------------------------|---------------------------------------|-------------------|
-| Infrastructure_MissingService | Service {0} is required.              | For logging only! |
-| Shopping_NoShipping           | We cannot ship {0} to {1}.            |                   |
-| Shopping_OutOfStock           | Product is out of stock at this time. |                   |
-
-The following code would be generated:
-
-```csharp
-partial class ThisAssembly
-{
-    public static partial class Strings
-    {
-        public static partial class Infrastructure
-        {
-            /// <summary>
-            /// For logging only!
-            /// => "Service {0} is required."
-            /// </summary>
-            public static string MissingService(object arg0)
-                => string.Format(CultureInfo.CurrentCulture, 
-                    Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("MissingService"), 
-                    arg0);
-        }
-
-        public static partial class Shopping
-        {
-            /// <summary>
-            /// => "We cannot ship {0} to {1}."
-            /// </summary>
-            public static string NoShipping(object arg0, object arg1)
-                => string.Format(CultureInfo.CurrentCulture, 
-                    Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("NoShipping"), 
-                    arg0, arg1);
-
-            /// <summary>
-            /// => "Product is out of stock at this time."
-            /// </summary>
-            public static string OutOfStock
-                => Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("OutOfStock");
-        }
-    }
-}
-```
+<!-- include src/ThisAssembly.Strings/readme.md#content -->
 
 # Dogfooding
 
 [![CI Version](https://img.shields.io/endpoint?url=https://shields.kzu.io/vpre/Stunts/main&label=nuget.ci&color=brightgreen)](https://pkg.kzu.io/index.json)
-[![Build](https://github.com/kzu/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/kzu/ThisAssembly/actions)
+[![Build](https://github.com/devlooped/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/devlooped/ThisAssembly/actions)
 
 We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced. 
 
@@ -209,11 +81,4 @@ The versioning scheme for packages is:
 - Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]`
 
 
-
-## Sponsors
-
-<h3 style="vertical-align: text-top" id="by-clarius">
-<img src="https://raw.githubusercontent.com/devlooped/oss/main/assets/images/sponsors.svg" alt="sponsors" height="36" width="36" style="vertical-align: text-top; border: 0px; padding: 0px; margin: 0px">&nbsp;&nbsp;by&nbsp;<a href="https://github.com/clarius">@clarius</a>&nbsp;<img src="https://raw.githubusercontent.com/clarius/branding/main/logo/logo.svg" alt="sponsors" height="36" width="36" style="vertical-align: text-top; border: 0px; padding: 0px; margin: 0px">
-</h3>
-
-*[get mentioned here too](https://github.com/sponsors/devlooped)!*
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.AssemblyInfo/readme.md b/src/ThisAssembly.AssemblyInfo/readme.md
@@ -0,0 +1,22 @@
+<!-- #content -->
+This package generates a static `ThisAssembly.Info` class with public 
+constants exposing the following attribute values generated by default for SDK style projects:
+
+* AssemblyConfigurationAttribute
+* AssemblyCompanyAttribute
+* AssemblyTitleAttribute
+* AssemblyDescriptionAttribute
+* AssemblyProductAttribute
+* AssemblyCopyrightAttribute
+
+* AssemblyVersionAttribute
+* AssemblyInformationalVersionAttribute
+* AssemblyFileVersionAttribute
+
+If your project includes these attributes by other means, they will still be emitted properly 
+on the `ThisAssembly.Info` class.
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.AssemblyInfo.png)
+
+<!-- #content -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Constants/readme.md b/src/ThisAssembly.Constants/readme.md
@@ -0,0 +1,29 @@
+<!-- #content -->
+This package generates a static `ThisAssembly.Constants` class with public
+constants for `@(Constant)` MSBuild items in the project.
+
+```xml
+  <ItemGroup>
+    <Constant Include="Foo.Bar" Value="Baz" Comment="Yay!" />
+    <Constant Include="Foo.Hello" Value="World" Comment="Comments make everything better 😍" />
+  </ItemGroup>
+```
+
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants.png)
+
+In addition to arbitrary constants via `<Constant ...>`, it's quite useful (in particular in test projects) 
+to generate constants for files in the project, so there's also a shorthand for those:
+
+```xml
+  <ItemGroup>
+    <FileConstant Include="@(Content)" />
+  </ItemGroup>
+```
+
+Which results in:
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants2.png)
+
+<!-- #content -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Metadata/readme.md b/src/ThisAssembly.Metadata/readme.md
@@ -0,0 +1,25 @@
+<!-- #content -->
+This package provides a static `ThisAssembly.Metadata` class with public 
+constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for 
+the project.
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Metadata.png)
+
+For an attribute declared (i.e. in *AssemblyInfo.cs*) like:
+
+```csharp
+[assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")]
+```
+
+A corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided. 
+The metadata attribute can alternatively be declared using MSBuild syntax in the project 
+(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items):
+
+```xml
+  <ItemGroup>
+    <AssemblyMetadata Include="Foo" Value="Bar" />
+  </ItemGroup>
+```
+
+<!-- #content -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Project/readme.md b/src/ThisAssembly.Project/readme.md
@@ -0,0 +1,20 @@
+<!-- #content -->
+This package generates a static `ThisAssembly.Project` class with public 
+constants exposing project properties that have been opted into this mechanism by adding 
+them as `ProjectProperty` MSBuild items in the project file, such as:
+
+```xml
+  <PropertyGroup>
+    <!-- Some arbitrary MSBuild property declared somewhere -->
+    <Foo>Bar</Foo>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- Opt-in to emitting that property value as a constant in ThisAssembly.Project -->
+    <ProjectProperty Include="Foo" />
+  </ItemGroup>
+```
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png)
+
+<!-- #content -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Resources/readme.md b/src/ThisAssembly.Resources/readme.md
@@ -0,0 +1,32 @@
+
+This package generates a static `ThisAssembly.Resources` class with public 
+properties exposing typed APIs to retrieve the contents of embedded resources.
+
+
+```xml
+  <ItemGroup>
+    <EmbeddedResource Include="Content/Docs/License.md" />
+  </ItemGroup>
+```
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources.png)
+
+Since markdown files are text files, the API will expose a `Text` property property 
+for it that will read its content once and cache it:
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources2.png)
+
+The `$(EmbeddedResourceStringExtensions)` MSBuild property allows customizing which 
+file extensions get treated as text files. By default, it's defined as:
+
+```xml
+  <PropertyGroup>
+    <EmbeddedResourceStringExtensions>.txt|.cs|.sql|.json|.md;</EmbeddedResourceStringExtensions>
+  </PropertyGroup>
+```
+
+You can always use the provided `GetStream` and `GetBytes` for more advanced scenarios (or for 
+non-text resources).
+
+<!-- #content -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->