docs: Update of Readme.md and documentation improvements.

Directory.Build.props

@@ -9,7 +9,7 @@
 
     <RepositoryType>git</RepositoryType>
     <RepositoryUrl>https://github.com/Heleonix/Heleonix.Build</RepositoryUrl>
-    <PackageProjectUrl>https://github.com/Heleonix/Heleonix.Build</PackageProjectUrl>
+    <PackageProjectUrl>https://heleonix.github.io/docs/Heleonix.Build/</PackageProjectUrl>
     <PackageIconUrl>https://raw.githubusercontent.com/Heleonix/docs/master/images/heleonix-logos/Heleonix-logo-128x128.jpg</PackageIconUrl>
 
     <IncludeSymbols>false</IncludeSymbols>
@@ -30,7 +30,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <LangVersion>latest</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <GenerateDocumentationFile>True</GenerateDocumentationFile>
+    <NoWarn>SA0001</NoWarn>
     <NeutralLanguage>en-US</NeutralLanguage>
     <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
   </PropertyGroup>

README.md

@@ -2,95 +2,51 @@
 
 [![Release: .NET / NuGet](https://github.com/Heleonix/Heleonix.Build/actions/workflows/release-net-nuget.yml/badge.svg)](https://github.com/Heleonix/Heleonix.Build/actions/workflows/release-net-nuget.yml)
 
-The MSBuild-based build framework for applications on CI and CD systems.
+The MSBuild-based build framework for applications on CI/CD systems.
 
 ## Install
 
 https://www.nuget.org/packages/Heleonix.Build
 
-## The main idea
+## The idea
 
-This framework is developed to simplify creation of scripts to build applications on CI/CD systems like GoCD, Jenkins, TeamCity etc.
+This framework is aiming to simplify implementation of different CI/CD stages for applications on CI/CD systems,
+like GoCD, Jenkins, TeamCity etc.
 
-The framework provides parameterized MSBuild targets, such as Hx_NetBuild, Hx_Coverlet, Hx_NetTest, Hx_Validate etc., which represent separate steps in CI pipelines.
+The build framework consists of parameterized MSBuild [Targets](https://heleonix.github.io/docs/Heleonix.Build/api/Targets/index.html),
+such as [Hx_NetBuild](https://heleonix.github.io/docs/Heleonix.Build/api/Targets/Hx_NetBuild.html),
+[Hx_NetTest](https://heleonix.github.io/docs/Heleonix.Build/api/Targets/Hx_NetTest.html),
+[Hx_NetValidate](https://heleonix.github.io/docs/Heleonix.Build/api/Targets/Hx_NetValidate.html) etc.,
+which usually represent separate steps in CI pipelines.
 
-Since every company has some custom standards of source code arrangement, this build framework supports solid customization.
-Basically it follows the "configurable conventions" approach.
+The build framework also provides set of reusable [Tasks](https://heleonix.github.io/docs/Heleonix.Build/api/Tasks/index.html).
 
-Default values of properties of MSBuild targets follow well-known pracices of arrangement of source code.
-So, if you follow standards as well, you do not even neeed to write custom build scripts, like "Build.props", "MyProjectBuild.targets", "bla-bla.props" etc.
+Usually source code is organized by following some well-known or custom standards, that's why this build framework
+supports solid customization. Basically it follows the "configurable conventions" approach.
 
-## Writing custom scripts
+Default values of properties and items of [Targets](https://heleonix.github.io/docs/Heleonix.Build/api/Targets/index.html) follow well-known practices of arrangement of source code.
+So, if you follow well-known standards too, you do not even neeed to write custom build scripts.
 
-### Naming Conventions:
+## More details
 
-#### Global Property Name:
-`<Ns><_Sys | _WS | _Run>_<PropertyName>[Dir(s) | File(s) | Url(s) | <Ext>]`
+- [Usage](https://heleonix.github.io/docs/Heleonix.Build/usage.html)
+- [Extensibility](https://heleonix.github.io/docs/Heleonix.Build/extensibility.md)
+- [API](https://heleonix.github.io/docs/Heleonix.Build/api/Heleonix.Build.html)
 
-Global properties are defined out of targets, so they can be overriden in your custom *.hxbproj files out of targets or from the command line.
+## Contribution Guideline
 
-#### Target Name:
-`<Ns>_<TargetName>[_Variation]`
-Artifacts directory for all variations is the same
-`Ns_Int_*` supposed to be used within the framework and your custom targets internally, but not by CI/CD.
+1. [Create a fork](https://github.com/Heleonix/Heleonix.Build/fork) from the main repository
+2. Implement whatever is needed
+3. [Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+   Make sure the assigned [Checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks) pass successfully.
+   You can watch the progress in the [PR: .NET](https://github.com/Heleonix/Heleonix.Build/actions/workflows/pr-net.yml) GitHub workflows
+4. [Request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from the code owner
+5. Once approved, merge your Pull Request via [Squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)
 
-#### Target's Parameter Name:
-`<TargetName>_<ParameterName>[Dir(s) | File(s) | <Ext>]`
+   > [!IMPORTANT]  
+   > While merging, enter a [Conventional Commits](https://www.conventionalcommits.org/) commit message.
+   > This commit message will be used in automatically generated [Github Release Notes](https://github.com/Heleonix/Heleonix.Build/releases)
+   > and [NuGet Release Notes](https://www.nuget.org/packages/Heleonix.Build/#releasenotes-body-tab)
 
-If a parameter is a single item, then it should be an MSBuild property.
-If a parameter is multiple items (the name ending with (s)), then it should be an MSBuild item.
-
-#### Target's Private Parameter Name:
-`_<TargetName>_<ParameterName>[Dir(s) | File(s) | <Ext>]`
-
-#### Target's artifacts:
-The properties `Ns_TargetName_ArtifactsDir` defining paths to artifacts directories are defined out of targets, as the global properties,
-because targets can depend on each other via artifacts. I.e. Hx_ChangeLog_ArtifactsDir is used by Hx_NetBuild, Hx_NetNugetPush etc.
-
-Targets can depend on each other only via artifacts, because if every target is executed in a separate dotnet.exe run,
-then their properties and items are not defined.
-
-#### Target template
-
-```xml
-<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <PropertyGroup>
-    <Ns_TargetName_ArtifactsDir>$(Hx_Run_ArtifactsDir)/TargetName</Ns_TargetName_ArtifactsDir>
-  </PropertyGroup>
-
-  <Target Name="Ns_TargetName">
-    <Message Text="> RUNNING Ns_TargetName ..." Importance="high"/>
-
-    <Hx_NetSetupTool DotnetExe="$(Hx_Sys_DotnetExe)" Name="NameOfFile">
-      <Output TaskParameter="ToolPath" PropertyName="_Ns_TargetName_NameOfFileExe"/>
-    </Hx_NetSetupTool>
-
-    <!--Validation of required parameters-->
-
-    <!--Target's property groups, setting default vaues-->
-
-    <!--Target's item groups, setting default values-->
-
-    <Message Text="> 1/3: Doing step one" Importance="high"/>
-    <!--tasks, targets etc.-->
-    <!--tasks, targets etc.-->
-
-    <Message Text="> 2/3: Doing step two" Importance="high"/>
-    <!--tasks, targets etc.-->
-    <!--tasks, targets etc.-->
-
-    <Message Text="> 3/3: Doing step three" Importance="high"/>
-    <!--tasks, targets etc.-->
-    <!--tasks, targets etc.-->
-
-    <Message Text="> DONE Ns_TargetName" Importance="high"/>
-
-    <OnError ExecuteTargets="Hx_OnError"/>
-  </Target>
-</Project>
-```
-
-### Notes
-Use slash `/` in paths in MSBuild scripts, not backslash `\`, because MSBuild replaces them on *nix OSs anyway
-
-Use slash `/` in path regular expressions in Heleonix.Build tasks.
+5. Monitor the [Release: .NET / NuGet](https://github.com/Heleonix/Heleonix.Build/actions/workflows/release-net-nuget.yml) GitHub workflow to make sure your changes are delivered successfully
+5. In case of any issues, please contact [[email protected]](mailto:[email protected])

src/Heleonix.Build/GlobalSuppressions.cs

@@ -7,3 +7,4 @@
 
 [assembly: SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1623:Property summary documentation should match accessors", Justification = "MSBuild tasks are not regular library classes.", Scope = "module")]
 [assembly: SuppressMessage("Minor Code Smell", "S101:Types should be named in PascalCase", Justification = "The 'Hx_' prefix in class names is used to avoid task name conflicts in MSBuild scripts.", Scope = "module")]
+[assembly: SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1600:Elements should be documented", Justification = "Tasks are documented in xsd schemas.", Scope = "module")]

src/Heleonix.Build/Program.cs

@@ -10,17 +10,8 @@ namespace Heleonix.Build;
 using System.Reflection;
 using System.Text;
 
-/// <summary>
-/// The entry class of the tool.
-/// </summary>
-/// <exclude/>
 public static class Program
 {
-    /// <summary>
-    /// The entry point of the tool.
-    /// </summary>
-    /// <param name="args">The command line arguments.</param>
-    /// <returns>An exit code.</returns>
     public static int Main(string[] args)
     {
         if (args.Length == 1

src/Heleonix.Build/Schemas/Heleonix.Build.xsd

@@ -30,59 +30,76 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <xs:include
-    schemaLocation="C:/Program Files/Microsoft Visual Studio/2022/Community/Xml/Schemas/1033/MSBuild/Microsoft.Build.Commontypes.xsd" />
   <xs:include schemaLocation="./Targets/Targets.xsd"/>
   <xs:include schemaLocation="./Tasks/Tasks.xsd"/>
 
   <xs:element name="Hx_Sys_DotnetExe" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>
-        A path to the dotnet.exe to be used by the relevant targets. It is passed in from the --exe CLI parameter.
+        A path to the 'dotnet.exe' to be used by the relevant targets. It is passed in from the '--exe' CLI parameter.
         Default is 'dotnet.exe', considering it is globally available.
       </xs:documentation>
     </xs:annotation>
   </xs:element>
 
   <xs:element name="Hx_WS_Dir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A current folder, where build is executed. Usually, it's a folder where a repository was checked out.</xs:documentation>
+      <xs:documentation>
+        A current working folder, where 'hxbuild' is executed. Usually, it's a folder where a repository was checked out.
+        Default value is the $MSBuildStartupDirectory.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_WS_BuildProjFile" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>The build project file defining workspace-specific overrides.</xs:documentation>
+      <xs:documentation>
+        The MSBuild project file defining workspace-specific overrides.
+        This file is imported after the $Hx_Run_BuildProjFile and overrides evaluation-phase definitions of properties and items.
+        Default is '$Hx_WS_Dir/*.hxbproj'.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_WS_RepositoryUrl" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A url of the repository. Depends on the VCS. For example: https://github.com/Heleonix/Heleonix.Build.git.</xs:documentation>
+      <xs:documentation>
+        A url of the repository. Depends on the VCS. For example: https://github.com/Heleonix/Heleonix.Build.git.
+        Default tries to get it from:
+        $GO_MATERIAL_URL, $GIT_URL, $CI_REPOSITORY_URL, '$(GITHUB_SERVER_URL)/$(GITHUB_REPOSITORY).git'.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_WS_RepositoryAPIUrl" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A url of the repository API. Depends on the VCS. Default: https://api.github.com</xs:documentation>
+      <xs:documentation>A url of the repository API. Depends on the VCS. Default is https://api.github.com</xs:documentation>
     </xs:annotation>
   </xs:element>
 
   <xs:element name="Hx_Run_BuildProjFile" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A file to override everything up to solution-specific definitions.</xs:documentation>
+      <xs:documentation>
+        The MSBuild project file defining run-specific overrides. This file is imported before the $Hx_WS_BuildProjFile.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_Run_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A path to the root artifacts directory, where targets produce their artifacts.</xs:documentation>
+      <xs:documentation>
+        A path to the root artifacts directory, where targets produce their artifacts.
+        Default is '$Hx_WS_Dir/Hx_Artifacts'.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_Run_Configuration" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A configuration, i.e. "Release", "Debug" etc.</xs:documentation>
+      <xs:documentation>A configuration, i.e. 'Release', 'Debug' etc. Default is 'Release'.</xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_Run_Number" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A unique numeric value of the incremental build from your CI/CD system (GitHub Actions, GitLab CI/CD, Jenkins, TeamCity, GoCD etc.).</xs:documentation>
+      <xs:documentation>
+        A numeric value of the incremental build from your CI/CD system.
+        Default tries to take it from $GO_PIPELINE_COUNTER, $BUILD_NUMBER, $GITHUB_RUN_NUMBER, $CI_PIPELINE_ID or '0' otherwise.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
 </xs:schema>

src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd

@@ -30,26 +30,28 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <xs:include
-    schemaLocation="C:/Program Files/Microsoft Visual Studio/2022/Community/Xml/Schemas/1033/MSBuild/Microsoft.Build.Commontypes.xsd" />
-
   <xs:element name="Hx_ChangeLog_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A path to the ChangeLog artifacts directory.</xs:documentation>
+      <xs:documentation>
+        A path to the ChangeLog artifacts directory. Default is '$Hx_Run_ArtifactsDir/ChangeLog'.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
 
   <xs:element name="Hx_ChangeLog_TemplateFiles" type="msb:SimpleItemType" substitutionGroup="msb:Item">
     <xs:annotation>
       <xs:documentation>
-        The list of template files to generates change logs from.
-        Default are 'ReleaseNotes.md.cshtml' and 'ReleaseNotes.txt.cshtml' from the Heleonix.Build.
+        The list of Razor *.cshtml template files to generates change logs with using the Hx_FileRazorGenerate task.
+        Default are two templates: 'ReleaseNotes.md.cshtml' and 'ReleaseNotes.txt.cshtml' from the Heleonix.Build.
       </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_ChangeLog_CustomChanges" type="msb:GenericItemType" substitutionGroup="msb:Item">
     <xs:annotation>
-      <xs:documentation>The list of custom changes with custom metadata to generate change logs with.</xs:documentation>
+      <xs:documentation>
+        The list of custom changes with custom metadata to be passed into the Razor *.cshtml templates via the 'Data'
+        input property of the Hx_FileRazorGenerate task to generate change logs.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
 </xs:schema>

src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd

@@ -30,17 +30,17 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <xs:include
-    schemaLocation="C:/Program Files/Microsoft Visual Studio/2022/Community/Xml/Schemas/1033/MSBuild/Microsoft.Build.Commontypes.xsd" />
-
   <xs:element name="Hx_ChangeLog_GitHubCommit_Token" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A personal GitHub access token to authorize to the GitHub Releases API.</xs:documentation>
+      <xs:documentation>A GitHub access token to authorize to the GitHub Releases API.</xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_ChangeLog_GitHubCommit_VersionTagRegExp" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A regular expression to extract a version from a tag name of the latest release in format 11.22.33.</xs:documentation>
+      <xs:documentation>
+        A regular expression to extract a version from a tag name of the latest release.
+        Default regular expression parses versions in the format '11.22.33'.
+      </xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_ChangeLog_GitHubCommit_MajorChangeRegExp" type="msb:StringPropertyType" substitutionGroup="msb:Property">

src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd

@@ -30,12 +30,9 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <xs:include
-    schemaLocation="C:/Program Files/Microsoft Visual Studio/2022/Community/Xml/Schemas/1033/MSBuild/Microsoft.Build.Commontypes.xsd" />
-
   <xs:element name="Hx_DocFX_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
-      <xs:documentation>A path to the DocFX artifacts directory.</xs:documentation>
+      <xs:documentation>A path to the DocFX artifacts directory. Default is '$Hx_Run_ArtifactsDir/DocFX'.</xs:documentation>
     </xs:annotation>
   </xs:element>
   <xs:element name="Hx_DocFX_RepositoryUrl" type="msb:StringPropertyType" substitutionGroup="msb:Property">
@@ -46,7 +43,7 @@ Example custom property that allows string content only
   <xs:element name="Hx_DocFX_Message" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>
-        The commit message to commit and upload the generated documentation back to the repository url.
+        The commit message to commit and upload the generated documentation back to the $Hx_DocFX_RepositoryUrl.
         Default is 'Automatic update of documentation.'.
       </xs:documentation>
     </xs:annotation>