Skip to content

Commit 18ce9fd

Browse files
kzukzu
committed
Aggregate individual package readmes into meta-package
This involves not copying the readme to output (since includes should be relative to the source location, not the bin folder). Also renamed the anchors in each to avoid confusion. Expansion on the main readme should happen in the next automatic PR from include workflow.
1 parent b0bfe45 commit 18ce9fd

File tree

11 files changed

+57
-331
lines changed

11 files changed

+57
-331
lines changed

‎readme.md

Lines changed: 9 additions & 314 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[![License](https://img.shields.io/github/license/devlooped/ThisAssembly.svg?color=blue)](https://github.com//devlooped/ThisAssembly/blob/main/license.txt)
77
[![Build](https://github.com/devlooped/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/devlooped/ThisAssembly/actions)
88

9-
9+
<!-- #meta -->
1010
Exposes project and assembly level information as constants in the ThisAssembly
1111
class using source generators powered by Roslyn.
1212

@@ -21,223 +21,41 @@ all the other packages for convenience.
2121

2222
> [!NOTE]
2323
> For now, ThisAssembly only generates C# code.
24+
<!-- #meta -->
2425
2526
## ThisAssembly.AssemblyInfo
26-
2727
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.AssemblyInfo.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
2828
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.AssemblyInfo.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
2929

30-
<!-- include src/ThisAssembly.AssemblyInfo/readme.md#content -->
31-
<!-- #content -->
32-
This package generates a static `ThisAssembly.Info` class with public
33-
constants exposing the following attribute values generated by default for SDK style projects:
34-
35-
* AssemblyConfigurationAttribute
36-
* AssemblyCompanyAttribute
37-
* AssemblyTitleAttribute
38-
* AssemblyDescriptionAttribute
39-
* AssemblyProductAttribute
40-
* AssemblyCopyrightAttribute
41-
42-
* AssemblyVersionAttribute
43-
* AssemblyInformationalVersionAttribute
44-
* AssemblyFileVersionAttribute
45-
46-
If your project includes these attributes by other means, they will still be emitted properly
47-
on the `ThisAssembly.Info` class.
48-
49-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.AssemblyInfo.png)
50-
51-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
52-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
53-
54-
<!-- #content -->
55-
<!-- src/ThisAssembly.AssemblyInfo/readme.md#content -->
30+
<!-- include src/ThisAssembly.AssemblyInfo/readme.md#assembly -->
5631

5732
## ThisAssembly.Constants
5833

5934
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Constants.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Constants)
6035
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Constants.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Constants)
6136

62-
<!-- include src/ThisAssembly.Constants/readme.md#content -->
63-
<!-- #content -->
64-
This package generates a static `ThisAssembly.Constants` class with public
65-
constants for `@(Constant)` MSBuild items in the project.
66-
67-
```xml
68-
<ItemGroup>
69-
<Constant Include="Foo.Bar" Value="Baz" Comment="Yay!" />
70-
<Constant Include="Foo.Hello" Value="World" Comment="Comments make everything better 😍" />
71-
</ItemGroup>
72-
```
73-
74-
75-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants.png)
76-
77-
In addition to arbitrary constants via `<Constant ...>`, it's quite useful (in particular in test projects)
78-
to generate constants for files in the project, so there's also a shorthand for those:
79-
80-
```xml
81-
<ItemGroup>
82-
<FileConstant Include="@(Content)" />
83-
</ItemGroup>
84-
```
85-
86-
Which results in:
87-
88-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants2.png)
89-
90-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
91-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
92-
93-
<!-- #content -->
94-
<!-- src/ThisAssembly.Constants/readme.md#content -->
37+
<!-- include src/ThisAssembly.Constants/readme.md#constants -->
9538

9639
## ThisAssembly.Git
9740

9841
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Git.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Git)
9942
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Git.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Git)
10043

101-
<!-- include src/ThisAssembly.Git/readme.md#content -->
102-
<!-- #content -->
103-
This package generates a static `ThisAssembly.Git` class with constants
104-
for the following Git properties from the current project:
105-
106-
* Commit
107-
* Sha (first 9 chars from Commit)
108-
* Root (normalized to forward slashes)
109-
* Url (if PublishRepositoryUrl=true)
110-
* Branch (from CI environment variables)
111-
112-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Git.png)
113-
114-
This package relies on your project's installed
115-
[Microsoft.SourceLink.*](https://www.nuget.org/packages?q=Microsoft.SourceLink)
116-
package reference according to your specific Git-based source control server
117-
(such as GitHub, Azure DevOps, BitBucket, etc).
118-
119-
The `Branch` property is populated from environment variables provided
120-
by the currently supported CI systems: GitHub Actions, Azure DevOps,
121-
AppVeyor, TeamCity, Travis CI, Circle CI, GitLab CI, Buddy, and Jenkins.
122-
123-
Whenever the CI system provides a pull request number, the branch name is
124-
`pr[NUMBER]`, such as `pr123`. This makes it easy to use it as a semver
125-
metadata label.
126-
127-
> Note: by default, the values of these constants are populated during
128-
"real" builds (that is, not IDE/design-time builds used to populate
129-
intellisense). This is to avoid negatively affecting the editor's
130-
performance. This means, however, that the properties will seem to
131-
always be empty when inspecting them in the IDE (although never at
132-
run-time). If you want to force population of these values for
133-
design-time builds, set the `EnableSourceControlManagerQueries` property to `true`.
134-
This property is defined and documented by
135-
[dotnet/sourcelink](https://github.com/dotnet/sourcelink/blob/main/src/SourceLink.Common/build/Microsoft.SourceLink.Common.props#L14).
136-
137-
At the MSBuild level, targets can take a dependency on the provided
138-
`InitializeGitInformation` target, which sets the equivalent properties
139-
named:
140-
141-
* RepositoryCommit
142-
* RepositorySha
143-
* RepositoryRoot
144-
* RepositoryUrl
145-
* RepositoryBranch
146-
147-
The names of these properties were chosen on purpose to match the
148-
properties used by [nuget pack](https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets#pack-target)
149-
and [nugetizer](https://github.com/devlooped/nugetizer) to populate
150-
the relevant package metadata.
151-
152-
So if you have a GitHub repository, installing these three packages
153-
will ensure you have the proper metadata out of the box and the simplest
154-
packaging experience possible:
155-
156-
```xml
157-
<Project Sdk="Microsoft.NET.Sdk">
158-
<PropertyGroup>
159-
<TargetFramework>netstandard2.0</TargetFramework>
160-
</PropertyGroup>
161-
162-
<ItemGroup>
163-
<PackageReference Include="Microsoft.SourceLink.GitHub" />
164-
<PackageReference Include="ThisAssembly.Git" />
165-
<PackageReference Include="NuGetizer" />
166-
</ItemGroup>
167-
</Project>
168-
```
169-
170-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
171-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
172-
173-
174-
<!-- #content -->
175-
<!-- src/ThisAssembly.Git/readme.md#content -->
44+
<!-- include src/ThisAssembly.Git/readme.md#git -->
17645

17746
## ThisAssembly.Metadata
17847

17948
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Metadata.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Metadata)
18049
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Metadata.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Metadata)
18150

182-
<!-- include src/ThisAssembly.Metadata/readme.md#content -->
183-
<!-- #content -->
184-
This package provides a static `ThisAssembly.Metadata` class with public
185-
constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for
186-
the project.
187-
188-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Metadata.png)
189-
190-
For an attribute declared (i.e. in *AssemblyInfo.cs*) like:
191-
192-
```csharp
193-
[assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")]
194-
```
195-
196-
A corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided.
197-
The metadata attribute can alternatively be declared using MSBuild syntax in the project
198-
(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items):
199-
200-
```xml
201-
<ItemGroup>
202-
<AssemblyMetadata Include="Foo" Value="Bar" />
203-
</ItemGroup>
204-
```
205-
206-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
207-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
208-
209-
<!-- #content -->
210-
<!-- src/ThisAssembly.Metadata/readme.md#content -->
51+
<!-- include src/ThisAssembly.Metadata/readme.md#metadata -->
21152

21253
## ThisAssembly.Project
21354

21455
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Project.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Project)
21556
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Project.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Project)
21657

217-
<!-- include src/ThisAssembly.Project/readme.md#content -->
218-
<!-- #content -->
219-
This package generates a static `ThisAssembly.Project` class with public
220-
constants exposing project properties that have been opted into this mechanism by adding
221-
them as `ProjectProperty` MSBuild items in the project file, such as:
222-
223-
```xml
224-
<PropertyGroup>
225-
<!-- Some arbitrary MSBuild property declared somewhere -->
226-
<Foo>Bar</Foo>
227-
</PropertyGroup>
228-
<ItemGroup>
229-
<!-- Opt-in to emitting that property value as a constant in ThisAssembly.Project -->
230-
<ProjectProperty Include="Foo" />
231-
</ItemGroup>
232-
```
233-
234-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png)
235-
236-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
237-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
238-
239-
<!-- #content -->
240-
<!-- src/ThisAssembly.Project/readme.md#content -->
58+
<!-- include src/ThisAssembly.Project/readme.md#project -->
24159

24260
## ThisAssembly.Resources
24361

@@ -247,137 +65,14 @@ generated `ThisAssembly` class. Otherwise, it will be generated in the global na
24765
This package generates a static `ThisAssembly.Resources` class with public
24866
properties exposing shortcuts to retrieve the contents of embedded resources.
24967

250-
<!-- include src/ThisAssembly.Resources/readme.md#content -->
251-
<!-- #content -->
252-
253-
This package generates a static `ThisAssembly.Resources` class with public
254-
properties exposing typed APIs to retrieve the contents of embedded resources.
255-
256-
257-
```xml
258-
<ItemGroup>
259-
<EmbeddedResource Include="Content/Docs/License.md" />
260-
</ItemGroup>
261-
```
262-
263-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources.png)
264-
265-
Since markdown files are text files, the API will expose a `Text` property property
266-
for it that will read its content once and cache it:
267-
268-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources2.png)
269-
270-
The `$(EmbeddedResourceStringExtensions)` MSBuild property allows customizing which
271-
file extensions get treated as text files. By default, it's defined as:
272-
273-
```xml
274-
<PropertyGroup>
275-
<EmbeddedResourceStringExtensions>.txt|.cs|.sql|.json|.md</EmbeddedResourceStringExtensions>
276-
</PropertyGroup>
277-
```
278-
279-
You can append additional file extensions to this list, or override it completely.
280-
The list must be pipe-separated.
281-
282-
You can always use the provided `GetStream` and `GetBytes` for more advanced scenarios (or for
283-
non-text resources).
284-
285-
Optionally, you can specify the `Kind` metadata for a specific `EmbeddedResource` you want
286-
treated as a text file:
287-
288-
```xml
289-
<EmbeddedResource Include="query.kql" Kind="Text" />
290-
```
291-
292-
You can also add a `Comment` item metadata attribute, which will be used as the `<summary>` XML
293-
doc for the generated member.
294-
295-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
296-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
297-
298-
<!-- #content -->
299-
<!-- src/ThisAssembly.Resources/readme.md#content -->
68+
<!-- include src/ThisAssembly.Resources/readme.md#resources -->
30069

30170
## ThisAssembly.Strings
30271

30372
[![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Strings.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Strings)
30473
[![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Strings.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Strings)
30574

306-
<!-- include src/ThisAssembly.Strings/readme.md#content -->
307-
<!-- #content -->
308-
309-
This package generates a static `ThisAssembly.Strings` class with public
310-
constants exposing string resources in .resx files or methods with the right number of
311-
parameters for strings that use formatting parameters.
312-
313-
![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Strings.gif)
314-
315-
In addition, it groups constants and methods in nested classes according to an optional
316-
underscore separator to organize strings. For example, *User_InvalidCredentials* can be
317-
accessed with *ThisAssembly.Strings.User.InvalidCredentials* if it contains a simple string,
318-
or as a method with the right number of parametres if its value has a format string.
319-
320-
Given the following Resx file:
321-
322-
| Name | Value | Comment |
323-
|-------------------------------|---------------------------------------|-------------------|
324-
| Infrastructure_MissingService | Service {0} is required. | For logging only! |
325-
| Shopping_NoShipping | We cannot ship {0} to {1}. | |
326-
| Shopping_OutOfStock | Product is out of stock at this time. | |
327-
| Shopping_AvailableOn | Product available on {date:yyyy-MM}. | |
328-
329-
The following code would be generated:
330-
331-
```csharp
332-
partial class ThisAssembly
333-
{
334-
public static partial class Strings
335-
{
336-
public static partial class Infrastructure
337-
{
338-
/// <summary>
339-
/// For logging only!
340-
/// => "Service {0} is required."
341-
/// </summary>
342-
public static string MissingService(object arg0)
343-
=> string.Format(CultureInfo.CurrentCulture,
344-
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("MissingService"),
345-
arg0);
346-
}
347-
348-
public static partial class Shopping
349-
{
350-
/// <summary>
351-
/// => "We cannot ship {0} to {1}."
352-
/// </summary>
353-
public static string NoShipping(object arg0, object arg1)
354-
=> string.Format(CultureInfo.CurrentCulture,
355-
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("NoShipping"),
356-
arg0, arg1);
357-
358-
/// <summary>
359-
/// => "Product is out of stock at this time."
360-
/// </summary>
361-
public static string OutOfStock
362-
=> Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("OutOfStock");
363-
364-
/// <summary>
365-
/// Product available on {date:yyyy-MM}.
366-
/// </summary>
367-
public static string AvailableOn(object date)
368-
=> string.Format(CultureInfo.CurrentCulture,
369-
Strings.GetResourceManager("ThisAssemblyTests.Resources").GetString("WithNamedFormat").Replace("{date:yyyy-MM}", "{0}"),
370-
((IFormattable)date).ToString("yyyy-MM", CultureInfo.CurrentCulture));
371-
}
372-
}
373-
}
374-
```
375-
376-
Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the
377-
generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
378-
379-
<!-- #content -->
380-
<!-- src/ThisAssembly.Strings/readme.md#content -->
75+
<!-- include src/ThisAssembly.Strings/readme.md#strings -->
38176

38277
# Dogfooding
38378

‎src/Directory.Build.targets

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242

4343
<None Update="@(None -> WithMetadataValue('Filename', 'readme'))"
4444
Pack="true" PackagePath="%(Filename)%(Extension)"
45+
CopyToOutputDirectory="Never"
4546
Condition="'$(PackReadme)' != 'false' and '$(PackageReadmeFile)' != ''" />
4647

4748
<!-- src-level will need explicit inclusion -->
@@ -51,6 +52,7 @@
5152

5253
<None Include="$(MSBuildThisFileDirectory)readme.md" Link="readme.md"
5354
Pack="true" PackagePath="%(Filename)%(Extension)"
55+
CopyToOutputDirectory="Never"
5456
Condition="'$(PackReadme)' != 'false' and Exists('$(MSBuildThisFileDirectory)readme.md') and !Exists('$(MSBuildProjectDirectory)\readme.md')" />
5557
</ItemGroup>
5658

0 commit comments

Comments
 (0)