Added code quality updates (#298)

README.md

@@ -18,7 +18,7 @@ Please search the existing issues before filing new issues to avoid duplicates.
 - For new issues, file your bug or feature request as a new [issue].
 - For help, discussion, and support questions about using this project, join or start a [discussion].
 
-If you have any problems with the [PSDocs][engine] engine, please check the project GitHub [issues](https://github.com/BernieWhite/PSDocs/issues) page instead.
+If you have any problems with the [PSDocs][engine] engine, please check the project GitHub [issues](https://github.com/microsoft/PSDocs/issues) page instead.
 
 Support for this project/ product is limited to the resources listed above.
 

docs/install-instructions.md

@@ -21,15 +21,15 @@ You can also use this option to install on CI workers that are not natively supp
 The following platforms are supported:
 
 - Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater.
-- PowerShell 7.1 or greater on MacOS, Linux, and Windows.
+- PowerShell 7.3 or greater on MacOS, Linux, and Windows.
 
 PSDocs for Azure requires the PSDocs PowerShell module.
 The required version of PSDocs will automatically be installed along-side PSDocs for Azure.
 
 ### Installing PowerShell
 
 PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default.
-For a list of platforms that PowerShell 7.1 is supported on and install instructions see [Get PowerShell][3].
+For a list of platforms that PowerShell 7.3 is supported on and install instructions see [Get PowerShell][3].
 
   [3]: https://github.com/PowerShell/PowerShell#get-powershell
 

docs/overview.md

@@ -16,7 +16,7 @@ PSDocs for Azure includes pre-built functions and templates that make it easy to
 - **:octicons-people-24: Consumable** — Transform infrastructure code into presentable documentation.
   Use standard documentation that make it easier to deploy Azure resources.
 
-  [1]: https://github.com/BernieWhite/PSDocs
+  [1]: https://github.com/microsoft/PSDocs
 
 ## Ready to go
 

src/PSDocs.Azure/Configuration/OutputOption.cs

@@ -13,7 +13,7 @@ public sealed class OutputOption : IEquatable<OutputOption>
     {
         private const OutputEncoding DEFAULT_ENCODING = OutputEncoding.Default;
 
-        internal static readonly OutputOption Default = new OutputOption
+        internal static readonly OutputOption Default = new()
         {
             Encoding = DEFAULT_ENCODING
         };
@@ -49,7 +49,7 @@ public override int GetHashCode()
         {
             unchecked // Overflow is fine
             {
-                int hash = 17;
+                var hash = 17;
                 hash = hash * 23 + (Encoding.HasValue ? Encoding.Value.GetHashCode() : 0);
                 hash = hash * 23 + (Path != null ? Path.GetHashCode() : 0);
                 return hash;

src/PSDocs.Azure/Configuration/PSDocumentOption.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation.
+// Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
 using System.Diagnostics;
@@ -12,9 +12,12 @@ namespace PSDocs.Azure.Configuration
     /// </summary>
     internal delegate string PathDelegate();
 
+    /// <summary>
+    /// The base class for configuring options within PSDocs.
+    /// </summary>
     public sealed class PSDocumentOption
     {
-        internal static readonly PSDocumentOption Default = new PSDocumentOption
+        internal static readonly PSDocumentOption Default = new()
         {
             Output = OutputOption.Default
         };
@@ -24,6 +27,9 @@ public sealed class PSDocumentOption
         /// </summary>
         private static PathDelegate _GetWorkingPath = () => Directory.GetCurrentDirectory();
 
+        /// <summary>
+        /// Create an instance of options.
+        /// </summary>
         public PSDocumentOption()
         {
             // Set defaults
@@ -52,6 +58,9 @@ public static void UseExecutionContext(EngineIntrinsics executionContext)
             _GetWorkingPath = () => executionContext.SessionState.Path.CurrentFileSystemLocation.Path;
         }
 
+        /// <summary>
+        /// Get the current working path.
+        /// </summary>
         public static string GetWorkingPath()
         {
             return _GetWorkingPath();

src/PSDocs.Azure/PSDocs.Azure.csproj

@@ -4,31 +4,72 @@
     <TargetFramework>netstandard2.0</TargetFramework>
     <OutputType>Library</OutputType>
     <ProjectGuid>{1DF0509F-4D84-445F-BB98-CEA69EDD68FE}</ProjectGuid>
-    <!-- <DebugType>portable</DebugType> -->
+    <LangVersion>9.0</LangVersion>
     <NeutralLanguage>en-US</NeutralLanguage>
     <DebugSymbols>true</DebugSymbols>
+    <DebugType>portable</DebugType>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <EmbedUntrackedSources>true</EmbedUntrackedSources>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <GenerateAssemblyInfo>true</GenerateAssemblyInfo>
-    <!-- <TreatWarningsAsErrors>true</TreatWarningsAsErrors> -->
-    <Authors>Bernie White</Authors>
-    <AssemblyTitle>PSDocs</AssemblyTitle>
+    <PackageId>Microsoft.PSDocs.Azure.Core</PackageId>
+    <EnableNuget>false</EnableNuget>
+    <IsPackable>false</IsPackable>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+  </PropertyGroup>
+
+  <!-- Package metadata -->
+  <PropertyGroup>
+    <Authors>Microsoft</Authors>
+    <AssemblyTitle>PSDocs for Azure</AssemblyTitle>
     <RepositoryUrl>https://github.com/Azure/PSDocs.Azure</RepositoryUrl>
-    <PackageLicenseExpression>https://github.com/Azure/PSDocs.Azure/blob/main/LICENSE</PackageLicenseExpression>
+    <RepositoryType>git</RepositoryType>
+    <PackageProjectUrl>https://aka.ms/ps-docs-azure</PackageProjectUrl>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
+    <PackageTags>PSDocs;Azure;Bicep;IaC;markdown;documentation;</PackageTags>
     <Version>0.0.1</Version>
-    <Copyright>Copyright (c) Microsoft Corporation. Licensed under the MIT License.</Copyright>
+    <Company>Microsoft Corporation</Company>
+    <Copyright>&#169; Microsoft Corporation. All rights reserved.</Copyright>
     <Description>Generate markdown from Azure infrastructure as code (IaC) artifacts.
 
-This project uses GitHub Issues to track bugs and feature requests. See GitHub project for more information.</Description>
-  </PropertyGroup>
-
-  <PropertyGroup>
-    <AnalysisMode>AllEnabledByDefault</AnalysisMode>
-    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+      This project uses GitHub Issues to track bugs and feature requests. See GitHub project for
+      more information.</Description>
+    <PackageReleaseNotes>For a list of changes see https://aka.ms/ps-rule-docs.</PackageReleaseNotes>
+    <PackageIcon>package_icon.png</PackageIcon>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(OS)' == 'Windows_NT'">
     <DefineConstants>Windows</DefineConstants>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
+    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
+    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="..\..\docs\assets\package_icon.png">
+      <Pack>True</Pack>
+      <PackagePath>\</PackagePath>
+    </None>
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(PackageReadmeFile)' != ''">
+    <None Include="README.md">
+      <Pack>True</Pack>
+      <PackagePath>\</PackagePath>
+    </None>
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="7.0.4">
       <PrivateAssets>all</PrivateAssets>

src/PSDocs.Azure/Pipeline/Output/PSPipelineWriter.cs

@@ -1,9 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSDocs.Azure.Configuration;
 using System;
 using System.Management.Automation;
+using PSDocs.Azure.Configuration;
 
 namespace PSDocs.Azure.Pipeline.Output
 {

src/PSDocs.Azure/Pipeline/PathBuilder.cs

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSDocs.Azure.Configuration;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.IO;
+using PSDocs.Azure.Configuration;
 
 namespace PSDocs.Azure.Pipeline
 {
@@ -61,7 +61,7 @@ private void FindFiles(string path)
             if (TryAddFile(path))
                 return;
 
-            var pathLiteral = GetSearchParameters(path, out string searchPattern, out SearchOption searchOption);
+            var pathLiteral = GetSearchParameters(path, out var searchPattern, out var searchOption);
             if (TryAddFile(pathLiteral))
                 return;
 
@@ -100,7 +100,7 @@ private string GetRootedPath(string path)
         private string GetSearchParameters(string path, out string searchPattern, out SearchOption searchOption)
         {
             searchOption = SearchOption.AllDirectories;
-            var pathLiteral = SplitSearchPath(TrimPath(path, out bool relativeAnchor), out searchPattern);
+            var pathLiteral = SplitSearchPath(TrimPath(path, out var relativeAnchor), out searchPattern);
             if (string.IsNullOrEmpty(searchPattern))
                 searchPattern = _DefaultSearchPattern;
 

src/PSDocs.Azure/Pipeline/PipelineBuilder.cs

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSDocs.Azure.Configuration;
-using PSDocs.Azure.Pipeline.Output;
 using System;
 using System.Management.Automation;
+using PSDocs.Azure.Configuration;
+using PSDocs.Azure.Pipeline.Output;
 
 namespace PSDocs.Azure.Pipeline
 {

src/PSDocs.Azure/Pipeline/PipelineWriter.cs

@@ -1,11 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSDocs.Azure.Configuration;
 using System;
 using System.Collections.Generic;
 using System.Management.Automation;
 using System.Threading;
+using PSDocs.Azure.Configuration;
 
 namespace PSDocs.Azure.Pipeline
 {

src/PSDocs.Azure/Pipeline/TemplatePipeline.cs

@@ -1,17 +1,17 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using Newtonsoft.Json;
-using Newtonsoft.Json.Linq;
-using PSDocs.Azure.Configuration;
-using PSDocs.Azure.Data.Metadata;
-using PSDocs.Azure.Resources;
 using System;
 using System.Collections;
 using System.Globalization;
 using System.IO;
 using System.Management.Automation;
 using System.Threading;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using PSDocs.Azure.Configuration;
+using PSDocs.Azure.Data.Metadata;
+using PSDocs.Azure.Resources;
 
 namespace PSDocs.Azure.Pipeline
 {
@@ -65,7 +65,7 @@ internal TemplatePipeline(PipelineContext context, PipelineWriter writer, string
 
         public override void Process(PSObject sourceObject)
         {
-            if (sourceObject == null || !GetPath(sourceObject, out string path))
+            if (sourceObject == null || !GetPath(sourceObject, out var path))
                 return;
 
             _PathBuilder.Add(path);
@@ -81,19 +81,19 @@ private void ProcessTemplateFile(string templateFile)
                 var rootedTemplateFile = PSDocumentOption.GetRootedPath(templateFile);
 
                 // Check if metadata property exists
-                if (!TryTemplateFile(rootedTemplateFile, out string version, out JObject metadata))
+                if (!TryTemplateFile(rootedTemplateFile, out var version, out var metadata))
                     return;
 
                 var templateLink = new TemplateLink(rootedTemplateFile, version);
 
                 // Populate remaining properties
-                if (TryStringProperty(metadata, PROPERTYNAME_NAME, out string name))
+                if (TryStringProperty(metadata, PROPERTYNAME_NAME, out var name))
                     templateLink.Name = name;
 
-                if (TryStringProperty(metadata, PROPERTYNAME_DESCRIPTION, out string description))
+                if (TryStringProperty(metadata, PROPERTYNAME_DESCRIPTION, out var description))
                     templateLink.Description = description;
 
-                if (TryMetadata(metadata, out Hashtable meta))
+                if (TryMetadata(metadata, out var meta))
                     templateLink.Metadata = meta;
 
                 // var pso = PSObject.AsPSObject(templateLink);
@@ -157,7 +157,7 @@ private static T ReadFile<T>(string path)
         /// </summary>
         private static bool IsTemplateFile(JObject value)
         {
-            if (!value.TryGetValue(PROPERTYNAME_SCHEMA, out JToken token) || !Uri.TryCreate(token.Value<string>(), UriKind.Absolute, out Uri schemaUri))
+            if (!value.TryGetValue(PROPERTYNAME_SCHEMA, out var token) || !Uri.TryCreate(token.Value<string>(), UriKind.Absolute, out var schemaUri))
                 return false;
 
             return StringComparer.OrdinalIgnoreCase.Equals(schemaUri.Host, "schema.management.azure.com") &&
@@ -175,12 +175,12 @@ private bool TryTemplateFile(string templateFile, out string version, out JObjec
             if (jsonData == null || !IsTemplateFile(jsonData))
                 return false;
 
-            if (!(jsonData.TryGetValue(PROPERTYNAME_CONTENTVERSION, out JToken versionToken) && versionToken is JValue versionValue))
+            if (!(jsonData.TryGetValue(PROPERTYNAME_CONTENTVERSION, out var versionToken) && versionToken is JValue versionValue))
                 return false;
 
             version = versionValue.ToString();
             Writer.VerboseFoundTemplate(templateFile);
-            if (jsonData.TryGetValue(PROPERTYNAME_METADATA, out JToken metadataToken) && metadataToken is JObject metadataProperty)
+            if (jsonData.TryGetValue(PROPERTYNAME_METADATA, out var metadataToken) && metadataToken is JObject metadataProperty)
                 metadata = metadataProperty;
 
             if (metadata == null)
@@ -192,7 +192,7 @@ private bool TryTemplateFile(string templateFile, out string version, out JObjec
         private static bool TryStringProperty(JObject o, string propertyName, out string value)
         {
             value = null;
-            return o != null && o.TryGetValue(propertyName, out JToken token) && TryString(token, out value);
+            return o != null && o.TryGetValue(propertyName, out var token) && TryString(token, out value);
         }
 
         private static bool TryMetadata(JObject o, out Hashtable value)

src/PSDocs.Azure/README.md

@@ -0,0 +1,3 @@
+# PSDocs for Azure library for .NET
+
+Provides core functionality of PSDocs for Azure.