Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added code quality updates #298

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/install-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions src/PSDocs.Azure/Configuration/OutputOption.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,18 @@
{
private const OutputEncoding DEFAULT_ENCODING = OutputEncoding.Default;

internal static readonly OutputOption Default = new OutputOption
internal static readonly OutputOption Default = new()
{
Encoding = DEFAULT_ENCODING
};

public OutputOption()

Check warning on line 21 in src/PSDocs.Azure/Configuration/OutputOption.cs

View workflow job for this annotation

GitHub Actions / Build

Missing XML comment for publicly visible type or member 'OutputOption.OutputOption()'
{
Encoding = null;
Path = null;
}

public OutputOption(OutputOption option)

Check warning on line 27 in src/PSDocs.Azure/Configuration/OutputOption.cs

View workflow job for this annotation

GitHub Actions / Build

Missing XML comment for publicly visible type or member 'OutputOption.OutputOption(OutputOption)'
{
if (option == null)
throw new ArgumentNullException(nameof(option));
Expand All @@ -33,7 +33,7 @@
Path = option.Path;
}

public override bool Equals(object obj)

Check warning on line 36 in src/PSDocs.Azure/Configuration/OutputOption.cs

View workflow job for this annotation

GitHub Actions / Build

Missing XML comment for publicly visible type or member 'OutputOption.Equals(object)'
{
return obj is OutputOption option && Equals(option);
}
Expand All @@ -49,7 +49,7 @@
{
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;
Expand Down
13 changes: 11 additions & 2 deletions src/PSDocs.Azure/Configuration/PSDocumentOption.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright (c) Microsoft Corporation.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System.Diagnostics;
Expand All @@ -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
};
Expand All @@ -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
Expand Down Expand Up @@ -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();
Expand Down
65 changes: 53 additions & 12 deletions src/PSDocs.Azure/PSDocs.Azure.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion src/PSDocs.Azure/Pipeline/Output/PSPipelineWriter.cs
Original file line number Diff line number Diff line change
@@ -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
{
Expand Down
6 changes: 3 additions & 3 deletions src/PSDocs.Azure/Pipeline/PathBuilder.cs
Original file line number Diff line number Diff line change
@@ -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
{
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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;

Expand Down
4 changes: 2 additions & 2 deletions src/PSDocs.Azure/Pipeline/PipelineBuilder.cs
Original file line number Diff line number Diff line change
@@ -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
{
Expand Down
2 changes: 1 addition & 1 deletion src/PSDocs.Azure/Pipeline/PipelineWriter.cs
Original file line number Diff line number Diff line change
@@ -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
{
Expand Down
28 changes: 14 additions & 14 deletions src/PSDocs.Azure/Pipeline/TemplatePipeline.cs
Original file line number Diff line number Diff line change
@@ -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
{
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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") &&
Expand All @@ -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)
Expand All @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions src/PSDocs.Azure/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# PSDocs for Azure library for .NET

Provides core functionality of PSDocs for Azure.
Loading