Remove all XML help #3655

cormacpayne · 2017-03-20T22:00:56Z

Description

Fix for issue #3583

Remove all XML help from repository
Add script to build that will generate markdown help, compare it to what exists in the repository, validate the markdown help, and generate XML

This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices here.

I have read the contribution guidelines.
If changes were made to any cmdlet, the XML help was regenerated using the platyPSHelp module.
If any large changes are made to a service, they are reflected in the respective change log.

General Guidelines

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.
The pull request does not introduce breaking changes (unless a major version change occurs in the assembly and module).

Testing Guidelines

Pull request includes test coverage for the included changes.
PowerShell scripts used in tests should do any necessary setup as part of the test or suite setup, and should not use hard-coded values for locations or existing resources.

Cmdlet Signature Guidelines

New cmdlets that make changes or have side effects should implement ShouldProcess and have SupportShouldProcess=true specified in the cmdlet attribute. You can find more information on ShouldProcess here.
Cmdlet specifies OutputType attribute if any output is produced - if the cmdlet produces no output, it should implement a PassThru parameter.

Cmdlet Parameter Guidelines

Parameter types should not expose types from the management library - complex parameter types should be defined in the module.
Complex parameter types are discouraged - a parameter type should be simple types as often as possible. If complex types are used, they should be shallow and easily creatable from a constructor or another cmdlet.
Cmdlet parameter sets should be mutually exclusive - each parameter set must have at least one mandatory parameter not in other parameter sets.

…script to build.proj

cormacpayne · 2017-03-27T22:37:28Z

@azuresdkci test this please

…each cmdlet

…-Help.xml files that do not exist

cormacpayne · 2017-03-29T00:57:48Z

@markcowl resolved issue with wxi file

cormacpayne · 2017-03-29T21:24:19Z

Sign job: http://azuresdkci.cloudapp.net/view/1-AzurePowerShell/job/powershell-sign/938/

Update: sign job is passing 👍

…t being thrown during validation

markcowl · 2017-03-30T19:25:15Z

documentation/platyPSHelp-documentation.md

@@ -1,319 +0,0 @@
-# PlatyPS Help


Let's make sure to add in the new help documentation

markcowl · 2017-03-30T19:31:28Z

tools/StaticAnalysis/HelpAnalyzer/HelpAnalyzer.cs

+            }
+        }
+
+        private void ServiceManagementAnalyze(


<nit>AnalyzeMamlHelp</nit>

markcowl · 2017-03-30T19:32:13Z

tools/StaticAnalysis/HelpAnalyzer/HelpAnalyzer.cs

+                    }
+                    else
+                    {
+                        ResourceManagerAnalyze(directory, helpLogger, processedHelpFiles, savedDirectory);


<nit>AnalyzeMarkdownHelp</nit>

markcowl · 2017-03-30T19:39:16Z

tools/GenerateHelp.ps1


 # ---------------------------------------------------------------------------------------------

 if ($ValidateMarkdownHelp)
 {
    New-Item -Path "$PSScriptRoot\HelpGeneration\Exceptions" -Name NewValidateHelpExceptions.csv -ItemType File -Force | Out-Null

-    Add-Content "$PSscriptRoot\HelpGeneration\Exceptions\NewValidateHelpExceptions.csv" "Module,Target,Description"
+    Add-Content "$PSScriptRoot\HelpGeneration\Exceptions\NewValidateHelpExceptions.csv" "Module,Target,Description"


Generally, Exceptions are for expected errors, I think the error csvs are being copied to the build directory, and we should mnake sue of thsi same location Also, do we have any mechanism for suppressions?

markcowl

A few requested changes. Otherwise LGTM

markcowl · 2017-04-21T00:08:49Z

build.proj

 	<Message Importance="high" Text="Running Static Analyser" />
    <CallTarget targets="DependencyAnalysis" />
+    <Exec Command="$(PowerShellCommand) -NonInteractive -NoLogo -NoProfile -Command &quot;. $(LibraryToolsFolder)\CleanupBuild.ps1 -BuildConfig $(Configuration) &quot;"/>


Can we make sure the build fails if this fails? We can do this by settign ContinueOnError="false", similar to this: https://github.com/Azure/azure-powershell/blob/stack-dev/build.proj#L369

Also, lets make sure that building the installer always happens after generating help

markcowl · 2017-04-21T00:09:50Z

setup/azurecmdfiles.wxi

@@ -462,9 +462,6 @@
                        <Component Id="cmp6BDCB170E1F314882CF58F8F80DE76A6" Guid="*">
                            <File Id="filBFDE1699047559AB8DA89E0F660D35DF" KeyPath="yes" Source="$(var.sourceDir)\ResourceManager\AzureResourceManager\AzureRM.Billing\Microsoft.Azure.Commands.Common.Authentication.dll" />
                        </Component>
-                        <Component Id="cmpED253190CB7DAF0A995567435152DC6A" Guid="*">


These should not be deleted. We need the xml help files in the installer, or there will be no online help

@markcowl all dll-Help.xml references are still in the wxi file - the ones being removed are from projects with dependencies on other projects (e.g., Profile, Tags, Resources)

markcowl · 2017-04-21T00:24:27Z

tools/GenerateHelp.ps1

+Param(
+    [Parameter()]
+    [Switch]$ValidateMarkdownHelp,
+


<nit>remove extra veritcal space. You should only have a vertical space after a closing brace }, or the like </nit>

markcowl · 2017-04-21T00:28:36Z

tools/HelpGeneration/HelpGeneration.psm1

+    {
+        $HelpFolder = Get-Item $HelpFolderPath
+
+        $Exceptions = Import-Csv "$PSScriptRoot\..\..\src\Package\Exceptions\ValidateHelpExceptions.csv" | where { $_.Module -eq "$($HelpFolder.Parent.Name)" }


I think this should be a parameter

markcowl · 2017-04-21T00:30:09Z

tools/HelpGeneration/HelpGeneration.psm1

+        # If there were any errors recorded, print them out and throw
+        if ($errors.Count -gt 0)
+        {
+            $errors | foreach { Add-Content "$PSScriptRoot\..\..\src\Package\ValidateHelpExceptions.csv" $_ }


I think this outupe file should be a parameter. Also, I think you want this under src\Package\{buildconfig} by default in order to get it included in the build. Finally, this should be called ValdateHelpIssues.csv to be consistent with the other products of static analysis.

markcowl · 2017-04-21T00:30:46Z

tools/HelpGeneration/HelpGeneration.psm1

@@ -0,0 +1,343 @@
+#Requires -Modules platyPS


Same comment about extra vertical space, this applies throughout

…nto remove-xml-help # Conflicts: # src/ResourceManager/Compute/Commands.Compute/Commands.Compute.csproj # src/ResourceManager/Network/Commands.Network/Microsoft.Azure.Commands.Network.dll-Help.xml # src/ResourceManager/Sql/Commands.Sql/help/New-AzureRmSqlElasticPool.md

cormacpayne · 2017-04-21T22:10:52Z

Sign job: http://azuresdkci.cloudapp.net/view/1-AzurePowerShell/job/powershell-sign/969/

cormacpayne · 2017-04-24T22:35:59Z

@azuresdkci test this please

…nto remove-xml-help # Conflicts: # src/ResourceManager/Storage/Commands.Management.Storage/Microsoft.Azure.Commands.Management.Storage.dll-Help.xml # src/ResourceManager/Storage/Commands.Management.Storage/help/New-AzureRmStorageAccount.md # src/ResourceManager/Storage/Commands.Management.Storage/help/Set-AzureRmStorageAccount.md

…e-powershell into remove-xml-help

msftclas added the cla-not-required label Mar 20, 2017

markcowl assigned markcowl and unassigned markcowl Mar 21, 2017

This was referenced Mar 23, 2017

Updated external help for Microsoft.Compute #3624

Closed

Updated help for ASRRMcmdlets #3560

Closed

Update help documentation for Restore-AzureRmApiManagement #3660

Merged

cormacpayne added 6 commits March 24, 2017 17:21

Remove ARM and Storage XML help

1fcaf37

Refresh all markdown files based on content in repository

8810c06

Replace reference to XML in csproj with reference to help folder

d2c1a4b

Remove platyPSHelp module and documentation

6552818

Refresh wxi file

acb0a49

Add script and module to generate help, add exceptions file, and add …

17d0618

…script to build.proj

cormacpayne force-pushed the remove-xml-help branch from a593485 to 17d0618 Compare March 25, 2017 00:25

Refactor HelpAnalyzer to search for markdown instead of XML file for …

50d1885

…each cmdlet

cormacpayne assigned markcowl Mar 28, 2017

cormacpayne added the needs-review label Mar 28, 2017

cormacpayne changed the title ~~[DO NOT MERGE] Remove all XML help~~ Remove all XML help Mar 28, 2017

Revert changes made to wxi file, remove unnecessary references to dll…

279f355

…-Help.xml files that do not exist

Update csproj files with correct path for copying to Debug and Release

b529e15

Generate/validate help for Debug and Release, fix issue with error no…

8f57a46

…t being thrown during validation

markcowl requested changes Mar 30, 2017

View reviewed changes

documentation/platyPSHelp-documentation.md

@@ -1,319 +0,0 @@

# PlatyPS Help

Copy link

Member

markcowl Mar 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's make sure to add in the new help documentation

markcowl requested changes Mar 30, 2017

View reviewed changes

markcowl added needs-revision and removed needs-review labels Mar 30, 2017

markcowl assigned cormacpayne and unassigned markcowl Mar 30, 2017

cormacpayne mentioned this pull request Apr 14, 2017

Missing cmdlet help files in 3.8 release #3764

Closed

cormacpayne added needs-review and removed needs-revision labels Apr 17, 2017

cormacpayne assigned markcowl and unassigned cormacpayne Apr 17, 2017

markcowl requested changes Apr 21, 2017

View reviewed changes

markcowl assigned cormacpayne and unassigned markcowl Apr 21, 2017

markcowl added needs-revision and removed needs-review labels Apr 21, 2017

cormacpayne added 2 commits April 21, 2017 09:29

Resolve code review feedback

ce05522

cormacpayne added needs-review and removed needs-revision labels Apr 21, 2017

cormacpayne assigned markcowl and unassigned cormacpayne Apr 21, 2017

cormacpayne added 2 commits April 21, 2017 15:17

Add document for generating help

d90a7f4

Revert change in StaticAnalysis

0e1658d

markcowl assigned cormacpayne and unassigned markcowl Apr 24, 2017

markcowl previously approved these changes Apr 25, 2017

View reviewed changes

markcowl removed the needs-review label Apr 25, 2017

cormacpayne added 2 commits April 25, 2017 11:46

Merge branch 'remove-xml-help' of https://github.com/cormacpayne/azur…

a24e6a6

…e-powershell into remove-xml-help

cormacpayne dismissed markcowl’s stale review via a24e6a6 April 25, 2017 18:49

markcowl approved these changes Apr 25, 2017

View reviewed changes

markcowl merged commit c29bd5c into Azure:preview Apr 25, 2017

cormacpayne deleted the remove-xml-help branch August 7, 2017 16:28

Remove all XML help #3655

Remove all XML help #3655

Uh oh!

Conversation

cormacpayne commented Mar 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

cormacpayne commented Mar 27, 2017

Uh oh!

cormacpayne commented Mar 29, 2017

Uh oh!

cormacpayne commented Mar 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cormacpayne commented Apr 21, 2017

Uh oh!

cormacpayne commented Apr 24, 2017

Uh oh!

Uh oh!

cormacpayne commented Mar 20, 2017 •

edited

Loading

cormacpayne commented Mar 29, 2017 •

edited

Loading