add README.md for NuGet packages

smdn · May 2, 2023 · 901f631 · 901f631
1 parent 1c18b8d
commit 901f631
Show file tree

Hide file tree

Showing 10 changed files with 173 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -126,6 +126,7 @@ If there's a feature you would like to add or a bug you would like to fix, pleas
 IssueやPull Requestを送る際は、[Contribution guidelines](./CONTRIBUTING.md)をご覧頂ください。　可能なら英語が望ましいですが、日本語で構いません。
 
 # Notice
+<!-- #pragma section-start NupkgReadmeFile_Notice -->
 ## License
 This project is licensed under the terms of the [MIT License](./LICENSE.txt).
 
@@ -151,3 +152,4 @@ This project incorporates implementations partially ported from the following pr
 - [europowergenerators/Tapo-plug-controller](https://github.com/europowergenerators/Tapo-plug-controller)
 - [plasticrake/tplink-smarthome-api](https://github.com/plasticrake/tplink-smarthome-api/)
 - [plasticrake/tplink-smarthome-crypto](https://github.com/plasticrake/tplink-smarthome-crypto)
+<!-- #pragma section-end NupkgReadmeFile_Notice -->
diff --git a/examples/Smdn.TPSmartHomeDevices.Kasa/GettingStarted/README.md b/examples/Smdn.TPSmartHomeDevices.Kasa/GettingStarted/README.md
@@ -0,0 +1,4 @@
+# Notes
+The code in this example is to be included in the README of the NuGet package.
+
+Keep the content simple. Also, omit the license header.
diff --git a/examples/Smdn.TPSmartHomeDevices.MacAddressEndPoint/GettingStarted/README.md b/examples/Smdn.TPSmartHomeDevices.MacAddressEndPoint/GettingStarted/README.md
@@ -0,0 +1,4 @@
+# Notes
+The code in this example is to be included in the README of the NuGet package.
+
+Keep the content simple. Also, omit the license header.
diff --git a/examples/Smdn.TPSmartHomeDevices.Tapo/GettingStarted/README.md b/examples/Smdn.TPSmartHomeDevices.Tapo/GettingStarted/README.md
@@ -0,0 +1,4 @@
+# Notes
+The code in this example is to be included in the README of the NuGet package.
+
+Keep the content simple. Also, omit the license header.
diff --git a/src/Directory.Build.targets b/src/Directory.Build.targets
@@ -6,5 +6,6 @@ SPDX-License-Identifier: MIT
   <ImportGroup Label="project assets">
     <Import Project="$(SmdnProjectAssets_TargetsImports)" />
     <Import Project="$(MSBuildThisFileDirectory)PackageProvidedAPI.targets" />
+    <Import Project="$(MSBuildThisFileDirectory)ReadReadmeFileNoticeSectionContent.targets" />
   </ImportGroup>
 </Project>
diff --git a/src/ReadReadmeFileNoticeSectionContent.targets b/src/ReadReadmeFileNoticeSectionContent.targets
@@ -0,0 +1,33 @@
+<!--
+SPDX-FileCopyrightText: 2023 smdn <smdn@smdn.jp>
+SPDX-License-Identifier: MIT
+-->
+<Project>
+  <Target Name="ReadReadmeFileNoticeSectionContent">
+    <PropertyGroup>
+      <ReadmeFileNoticeSectionContent>$(
+        [System.IO.File]::ReadAllText('$(MSBuildThisFileDirectory)..\README.md')
+      )</ReadmeFileNoticeSectionContent>
+      <!-- extract section content -->
+      <ReadmeFileNoticeSectionContent>$([System.Text.RegularExpressions.Regex]::Replace(
+        '$(ReadmeFileNoticeSectionContent)',
+        '(?:.+)(?m-s:^.+-- #pragma section-start NupkgReadmeFile_Notice --.+$)(?&lt;notice&gt;.+)(?m-s:^.+-- #pragma section-end NupkgReadmeFile_Notice --.+$)(?:.+)',
+        '${notice}',
+        System.Text.RegularExpressions.RegexOptions.Singleline
+      ))</ReadmeFileNoticeSectionContent>
+      <!-- modify heading level -->
+      <ReadmeFileNoticeSectionContent>$([System.Text.RegularExpressions.Regex]::Replace(
+        '$(ReadmeFileNoticeSectionContent)',
+        '^##',
+        '###',
+        System.Text.RegularExpressions.RegexOptions.Multiline
+      ))</ReadmeFileNoticeSectionContent>
+      <!-- replace relative path to absolute, and trim whitespaces -->
+      <ReadmeFileNoticeSectionContent>$([System.Text.RegularExpressions.Regex]::Replace(
+        '$(ReadmeFileNoticeSectionContent)',
+        '\(\./([^\)]+)\)',
+        '($(RepositoryUrl)tree/main/$1)'
+      ).Trim())</ReadmeFileNoticeSectionContent>
+    </PropertyGroup>
+  </Target>
+</Project>
diff --git a/src/Smdn.TPSmartHomeDevices.Kasa/Smdn.TPSmartHomeDevices.Kasa.csproj b/src/Smdn.TPSmartHomeDevices.Kasa/Smdn.TPSmartHomeDevices.Kasa.csproj
@@ -23,14 +23,13 @@ SPDX-License-Identifier: MIT
   </PropertyGroup>
 
   <PropertyGroup Label="assembly attributes">
-    <Description>
-<![CDATA[Provides APIs for operating Kasa devices, the TP-Link smart home devices.
-]]></Description>
+    <Description>Provides APIs for operating Kasa devices, the TP-Link smart home devices.</Description>
     <CopyrightYear>2023</CopyrightYear>
   </PropertyGroup>
 
   <PropertyGroup Label="package properties">
     <PackageTags>tplink-kasa,kasa,HS105,KL130,$(PackageCommonTags)</PackageTags>
+    <GenerateNupkgReadmeFileDependsOnTargets>$(GenerateNupkgReadmeFileDependsOnTargets);GenerateReadmeFileContent</GenerateNupkgReadmeFileDependsOnTargets>
   </PropertyGroup>
 
   <PropertyGroup Label="StyleCop code analysis">
@@ -63,4 +62,41 @@ SPDX-License-Identifier: MIT
     />
   </ItemGroup>
 
+  <Target Name="GenerateReadmeFileContent" DependsOnTargets="ReadReadmeFileNoticeSectionContent">
+    <PropertyGroup>
+      <PackageReadmeFileContent><![CDATA[# $(PackageId) $(PackageVersion)
+`$(PackageId)` is a library that provides APIs for operating Kasa, the TP-Link smart home devices.
+This library performs operations by communicating directly with Kasa devices in the same network.
+
+This library also provides following features:
+
+- Automatic connection management, including reconnection.
+- Built-in/customizable error handling for typical errors and retries (like device busy, request timeout).
+- Using MAC address and following IP address change in DHCP networks (requires [Smdn.TPSmartHomeDevices.MacAddressEndPoint](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.MacAddressEndPoint/)).
+- `async` operation and cancellation.
+
+## Getting started
+First, add package `$(PackageId)` to the project file.
+
+```
+dotnet add package $(PackageId)
+```
+
+To operate the Kasa device, write code like the following. Replace the Kasa device's IP address with yours.
+
+```cs
+$([System.IO.File]::ReadAllText('$(MSBuildThisFileDirectory)..\..\examples\$(PackageId)\GettingStarted\Program.cs').TrimEnd())
+```
+
+More examples can be found on the [GitHub repository]($(RepositoryUrl)tree/main/examples/$(PackageId)/), including examples of using other Kasa devices and their functionalities, and examples of using library features.
+
+## Contributing
+This project welcomes contributions, feedbacks and suggestions. You can contribute to this project by submitting [Issues]($(RepositoryUrl)issues/new/choose) or [Pull Requests]($(RepositoryUrl)pulls/) on the [GitHub repository]($(RepositoryUrl)).
+
+## Notice
+$(ReadmeFileNoticeSectionContent)
+]]></PackageReadmeFileContent>
+    </PropertyGroup>
+  </Target>
+
 </Project>
diff --git a/...n.TPSmartHomeDevices.MacAddressEndPoint/Smdn.TPSmartHomeDevices.MacAddressEndPoint.csproj b/...n.TPSmartHomeDevices.MacAddressEndPoint/Smdn.TPSmartHomeDevices.MacAddressEndPoint.csproj
@@ -20,13 +20,14 @@ SPDX-License-Identifier: MIT
 
   <PropertyGroup Label="assembly attributes">
     <Description>
-<![CDATA[An extension library to add a service to Smdn.TPSmartHomeDevices.Kasa and Smdn.TPSmartHomeDevices.Tapo that enables the resolution of devices' endpoints by MAC address.
+<![CDATA[An extension library to add a service to Smdn.TPSmartHomeDevices.Tapo and Smdn.TPSmartHomeDevices.Kasa that enables the resolution of devices' endpoints by MAC address.
 ]]></Description>
     <CopyrightYear>2023</CopyrightYear>
   </PropertyGroup>
 
   <PropertyGroup Label="package properties">
     <PackageTags>tplink-kasa,kasa,tplink-tapo,tapo,mac-address,address-resolution,$(PackageCommonTags)</PackageTags>
+    <GenerateNupkgReadmeFileDependsOnTargets>$(GenerateNupkgReadmeFileDependsOnTargets);GenerateReadmeFileContent</GenerateNupkgReadmeFileDependsOnTargets>
   </PropertyGroup>
 
   <ItemGroup>
@@ -48,4 +49,30 @@ SPDX-License-Identifier: MIT
     />
   </ItemGroup>
 
+  <Target Name="GenerateReadmeFileContent" DependsOnTargets="ReadReadmeFileNoticeSectionContent">
+    <PropertyGroup>
+      <PackageReadmeFileContent><![CDATA[# $(PackageId) $(PackageVersion)
+`$(PackageId)` is an extension library for the [Smdn.TPSmartHomeDevices.Tapo](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Tapo/) and [Smdn.TPSmartHomeDevices.Kasa](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Kasa/)
+that enables to use MAC addresses to specify the device endpoints, instead of IP addresses or host names.
+
+This library also enables to support following changes of the device endpoint in network where IP addresses are dynamic, such as networks using DHCP.
+
+## Usage
+Add `MacAddressDeviceEndPointFactory` to the `ServiceCollection` and pass it as an `IServiceProvider` to the constructor of the [Tapo](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Tapo/) or [Kasa](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Kasa/) device class.
+
+```cs
+$([System.IO.File]::ReadAllText('$(MSBuildThisFileDirectory)..\..\examples\$(PackageId)\GettingStarted\Program.cs').TrimEnd())
+```
+
+More examples can be found on the [GitHub repository]($(RepositoryUrl)tree/main/examples/$(PackageId)/).
+
+## Contributing
+This project welcomes contributions, feedbacks and suggestions. You can contribute to this project by submitting [Issues]($(RepositoryUrl)issues/new/choose) or [Pull Requests]($(RepositoryUrl)pulls/) on the [GitHub repository]($(RepositoryUrl)).
+
+## Notice
+$(ReadmeFileNoticeSectionContent)
+]]></PackageReadmeFileContent>
+    </PropertyGroup>
+  </Target>
+
 </Project>
diff --git a/src/Smdn.TPSmartHomeDevices.Primitives/Smdn.TPSmartHomeDevices.Primitives.csproj b/src/Smdn.TPSmartHomeDevices.Primitives/Smdn.TPSmartHomeDevices.Primitives.csproj
@@ -19,7 +19,7 @@ SPDX-License-Identifier: MIT
 
   <PropertyGroup Label="assembly attributes">
     <Description>
-<![CDATA[Provides common types for Smdn.TPSmartHomeDevices.Kasa and Smdn.TPSmartHomeDevices.Tapo, including abstraction interfaces, extension methods and custom JsonConverter's.
+<![CDATA[Provides common types for Smdn.TPSmartHomeDevices.Tapo and Smdn.TPSmartHomeDevices.Kasa, including abstraction interfaces, extension methods and custom JsonConverter's.
 This library does not provide any specific implementations to operate Kasa and Tapo devices.
 ]]>
     </Description>
@@ -28,6 +28,7 @@ This library does not provide any specific implementations to operate Kasa and T
 
   <PropertyGroup Label="package properties">
     <PackageTags>tplink-kasa,kasa,tplink-tapo,tapo,common,$(PackageCommonTags)</PackageTags>
+    <GenerateNupkgReadmeFileDependsOnTargets>$(GenerateNupkgReadmeFileDependsOnTargets);GenerateReadmeFileContent</GenerateNupkgReadmeFileDependsOnTargets>
   </PropertyGroup>
 
   <PropertyGroup Label="StyleCop code analysis">
@@ -47,4 +48,21 @@ This library does not provide any specific implementations to operate Kasa and T
     <Compile Include="..\Common\System.Threading.Tasks\ValueTaskShim.cs" />
   </ItemGroup>
 
+  <Target Name="GenerateReadmeFileContent" DependsOnTargets="ReadReadmeFileNoticeSectionContent">
+    <PropertyGroup>
+      <PackageReadmeFileContent><![CDATA[# $(PackageId) $(PackageVersion)
+`$(PackageId)` is a library common to the [Smdn.TPSmartHomeDevices.Tapo](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Tapo/) and [Smdn.TPSmartHomeDevices.Kasa](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Kasa/)
+that provides types such as abstraction interfaces, extension methods and custom `JsonConverter`s.
+
+This library provides no specific implementations to operate Tapo and Kasa devices.
+
+## Contributing
+This project welcomes contributions, feedbacks and suggestions. You can contribute to this project by submitting [Issues]($(RepositoryUrl)issues/new/choose) or [Pull Requests]($(RepositoryUrl)pulls/) on the [GitHub repository]($(RepositoryUrl)).
+
+## Notice
+$(ReadmeFileNoticeSectionContent)
+]]></PackageReadmeFileContent>
+    </PropertyGroup>
+  </Target>
+
 </Project>
diff --git a/src/Smdn.TPSmartHomeDevices.Tapo/Smdn.TPSmartHomeDevices.Tapo.csproj b/src/Smdn.TPSmartHomeDevices.Tapo/Smdn.TPSmartHomeDevices.Tapo.csproj
@@ -23,14 +23,13 @@ SPDX-License-Identifier: MIT
   </PropertyGroup>
 
   <PropertyGroup Label="assembly attributes">
-    <Description>
-<![CDATA[Provides APIs for operating Tapo devices, the TP-Link smart home devices.
-]]></Description>
+    <Description>Provides APIs for operating Tapo devices, the TP-Link smart home devices.</Description>
     <CopyrightYear>2023</CopyrightYear>
   </PropertyGroup>
 
   <PropertyGroup Label="package properties">
     <PackageTags>tplink-tapo,tapo,L530,L900,P105,$(PackageCommonTags)</PackageTags>
+    <GenerateNupkgReadmeFileDependsOnTargets>$(GenerateNupkgReadmeFileDependsOnTargets);GenerateReadmeFileContent</GenerateNupkgReadmeFileDependsOnTargets>
   </PropertyGroup>
 
   <PropertyGroup Label="StyleCop code analysis">
@@ -65,4 +64,41 @@ SPDX-License-Identifier: MIT
     />
   </ItemGroup>
 
+  <Target Name="GenerateReadmeFileContent" DependsOnTargets="ReadReadmeFileNoticeSectionContent">
+    <PropertyGroup>
+      <PackageReadmeFileContent><![CDATA[# $(PackageId) $(PackageVersion)
+`$(PackageId)` is a library that provides APIs for operating Tapo, the TP-Link smart home devices.
+This library performs operations by communicating directly with Tapo devices in the same network.
+
+This library also provides following features:
+
+- Automatic connection/authentication/session management, including reconnection and re-authentication.
+- Built-in/customizable error handling for typical errors and retries (like device busy, session expired, request timeout).
+- Using MAC address and following IP address change in DHCP networks (requires [Smdn.TPSmartHomeDevices.MacAddressEndPoint](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.MacAddressEndPoint/)).
+- `async` operation and cancellation.
+
+## Getting started
+First, add package `$(PackageId)` to the project file.
+
+```
+dotnet add package $(PackageId)
+```
+
+To operate the Tapo device, write code like the following. Replace the Tapo device's IP address and Tapo account information with yours.
+
+```cs
+$([System.IO.File]::ReadAllText('$(MSBuildThisFileDirectory)..\..\examples\$(PackageId)\GettingStarted\Program.cs').TrimEnd())
+```
+
+More examples can be found on the [GitHub repository]($(RepositoryUrl)tree/main/examples/$(PackageId)/), including examples of using other Tapo devices and their functionalities, and examples of using library features.
+
+## Contributing
+This project welcomes contributions, feedbacks and suggestions. You can contribute to this project by submitting [Issues]($(RepositoryUrl)issues/new/choose) or [Pull Requests]($(RepositoryUrl)pulls/) on the [GitHub repository]($(RepositoryUrl)).
+
+## Notice
+$(ReadmeFileNoticeSectionContent)
+]]></PackageReadmeFileContent>
+    </PropertyGroup>
+  </Target>
+
 </Project>