diff --git a/README.md b/README.md index a4107ad..b1a9d62 100644 --- a/README.md +++ b/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. diff --git a/docs/install-instructions.md b/docs/install-instructions.md index 71c712c..39d5932 100644 --- a/docs/install-instructions.md +++ b/docs/install-instructions.md @@ -21,7 +21,7 @@ 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. @@ -29,7 +29,7 @@ The required version of PSDocs will automatically be installed along-side PSDocs ### 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 diff --git a/docs/overview.md b/docs/overview.md index 96faa3c..11d1b52 100644 --- a/docs/overview.md +++ b/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 diff --git a/src/PSDocs.Azure/Configuration/OutputOption.cs b/src/PSDocs.Azure/Configuration/OutputOption.cs index e26a812..d5c95a9 100644 --- a/src/PSDocs.Azure/Configuration/OutputOption.cs +++ b/src/PSDocs.Azure/Configuration/OutputOption.cs @@ -13,7 +13,7 @@ public sealed class OutputOption : IEquatable { 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; diff --git a/src/PSDocs.Azure/Configuration/PSDocumentOption.cs b/src/PSDocs.Azure/Configuration/PSDocumentOption.cs index 8a0190c..b761f24 100644 --- a/src/PSDocs.Azure/Configuration/PSDocumentOption.cs +++ b/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 /// internal delegate string PathDelegate(); + /// + /// The base class for configuring options within PSDocs. + /// 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 /// private static PathDelegate _GetWorkingPath = () => Directory.GetCurrentDirectory(); + /// + /// Create an instance of options. + /// public PSDocumentOption() { // Set defaults @@ -52,6 +58,9 @@ public static void UseExecutionContext(EngineIntrinsics executionContext) _GetWorkingPath = () => executionContext.SessionState.Path.CurrentFileSystemLocation.Path; } + /// + /// Get the current working path. + /// public static string GetWorkingPath() { return _GetWorkingPath(); diff --git a/src/PSDocs.Azure/PSDocs.Azure.csproj b/src/PSDocs.Azure/PSDocs.Azure.csproj index 55463ee..a347053 100644 --- a/src/PSDocs.Azure/PSDocs.Azure.csproj +++ b/src/PSDocs.Azure/PSDocs.Azure.csproj @@ -4,31 +4,72 @@ netstandard2.0 Library {1DF0509F-4D84-445F-BB98-CEA69EDD68FE} - + 9.0 en-US true + portable + true + snupkg + true + true true - - Bernie White - PSDocs + Microsoft.PSDocs.Azure.Core + false + false + README.md + + + + + Microsoft + PSDocs for Azure https://github.com/Azure/PSDocs.Azure - https://github.com/Azure/PSDocs.Azure/blob/main/LICENSE + git + https://aka.ms/ps-docs-azure + MIT + true + PSDocs;Azure;Bicep;IaC;markdown;documentation; 0.0.1 - Copyright (c) Microsoft Corporation. Licensed under the MIT License. + Microsoft Corporation + © Microsoft Corporation. All rights reserved. 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. - - - - AllEnabledByDefault - true + This project uses GitHub Issues to track bugs and feature requests. See GitHub project for + more information. + For a list of changes see https://aka.ms/ps-rule-docs. + package_icon.png Windows + + true + + + + true + + + + + + + + + True + \ + + + + + + True + \ + + + all diff --git a/src/PSDocs.Azure/Pipeline/Output/PSPipelineWriter.cs b/src/PSDocs.Azure/Pipeline/Output/PSPipelineWriter.cs index b3821c9..443fc15 100644 --- a/src/PSDocs.Azure/Pipeline/Output/PSPipelineWriter.cs +++ b/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 { diff --git a/src/PSDocs.Azure/Pipeline/PathBuilder.cs b/src/PSDocs.Azure/Pipeline/PathBuilder.cs index c041585..5cc5072 100644 --- a/src/PSDocs.Azure/Pipeline/PathBuilder.cs +++ b/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; diff --git a/src/PSDocs.Azure/Pipeline/PipelineBuilder.cs b/src/PSDocs.Azure/Pipeline/PipelineBuilder.cs index 3a662fa..3e2eff6 100644 --- a/src/PSDocs.Azure/Pipeline/PipelineBuilder.cs +++ b/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 { diff --git a/src/PSDocs.Azure/Pipeline/PipelineWriter.cs b/src/PSDocs.Azure/Pipeline/PipelineWriter.cs index 2cf35b0..879f9f7 100644 --- a/src/PSDocs.Azure/Pipeline/PipelineWriter.cs +++ b/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 { diff --git a/src/PSDocs.Azure/Pipeline/TemplatePipeline.cs b/src/PSDocs.Azure/Pipeline/TemplatePipeline.cs index 40cd9c0..5c50e3a 100644 --- a/src/PSDocs.Azure/Pipeline/TemplatePipeline.cs +++ b/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(string path) /// private static bool IsTemplateFile(JObject value) { - if (!value.TryGetValue(PROPERTYNAME_SCHEMA, out JToken token) || !Uri.TryCreate(token.Value(), UriKind.Absolute, out Uri schemaUri)) + if (!value.TryGetValue(PROPERTYNAME_SCHEMA, out var token) || !Uri.TryCreate(token.Value(), 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) diff --git a/src/PSDocs.Azure/README.md b/src/PSDocs.Azure/README.md new file mode 100644 index 0000000..a01c969 --- /dev/null +++ b/src/PSDocs.Azure/README.md @@ -0,0 +1,3 @@ +# PSDocs for Azure library for .NET + +Provides core functionality of PSDocs for Azure.