Generate docs for dotnet nuget commands.

scripts/utils/docsPRGen.ps1

@@ -0,0 +1,33 @@
+# This takes docs.md and helps create/update files for the dotnet docs repo.
+# https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md#process-for-contributing
+
+param (
+    [Parameter(Mandatory=$true)][string]$DotnetDocsRootDir
+ )
+
+$mdFile = "src\NuGet.Core\NuGet.CommandLine.XPlat\external\docs.md"
+$outFile = "";
+$todayShortDate = Get-Date -Format "MM/dd/yyyy"
+
+foreach($line in [System.IO.File]::ReadLines($mdFile))
+{
+    if ($line.StartsWith("---file:"))
+    {
+        $relativeDestFilePath = $line.SubString(8)
+        $outFile = "$DotnetDocsRootDir\$relativeDestFilePath"
+        Remove-Item "$outFile"
+        New-Item "$outFile" -ItemType file
+    }
+    elseif ($line.StartsWith("ms.date:"))
+    {
+        Add-Content "$outFile" "ms.date: $todayShortDate" -Encoding ASCII 
+    }
+    elseif ($line.StartsWith("***"))
+    {
+        #skip each line of the instructions at top of docs.md file
+    }
+    else
+    {
+        Add-Content "$outFile" $line -Encoding ASCII             
+    }
+}

scripts/utils/ttGen.ps1

@@ -0,0 +1,12 @@
+Write-Host "Regenerating all generated files from all .tt files."
+Write-Host "(requires t4.exe from 'dotnet tool install --global dotnet-t4' or right click .tt files in VS and 'run custom tool')"
+Write-Host ""
+$ttFiles = Get-ChildItem -Filter *.tt -Recurse -File -Name
+foreach ($ttFile in $ttFiles)
+{
+    if (-not $ttFile.endswith("AssemblySourceFileGenerator.tt"))
+    {
+        Write-Host t4.exe $ttFile
+        t4.exe "$ttFile"
+    }
+}

src/NuGet.Clients/NuGet.CommandLine/NuGetCommand.resx

@@ -389,7 +389,7 @@ nuget setapikey 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a -Source http://example.com/
     <comment>Only localize "[name]" and "[source]"</comment>
   </data>
   <data name="SourcesCommandUserNameDescription" xml:space="preserve">
-    <value>UserName to be used when connecting to an authenticated source.</value>
+    <value>Username to be used when connecting to an authenticated source.</value>
   </data>
   <data name="SpecCommandAssemblyPathDescription" xml:space="preserve">
     <value>Assembly to use for metadata.</value>

src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt

@@ -18,6 +18,11 @@
         return type == "Argument";
     }
 
+    bool IsOption(string type)
+    {
+        return type == "Option";
+    }
+
     string GetProperty(XElement element)
     {
         switch (element.Name.LocalName)
@@ -26,8 +31,14 @@
                 return "Option";
             case "SwitchOption":
                 return "Option";
+            case "Value":
+                return "Option";
             case "Argument":
                 return "Argument";
+            case "Example":
+                return "Example";
+            case "SeeAlso":
+                return "SeeAlso";
             default:
                 return "Unknown Element Type " + element.Name.LocalName;
         }

src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml

@@ -3,49 +3,82 @@
      Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. -->
 <Commands>
   <Verb Name="add">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200"
+       Description="adds a new package source to your NuGet configuration files."
+       >
       <Argument Name="Source" LongName="PackageSourcePath" Help="SourcesCommandSourceDescription" />
       <SingleValueOption Name="name" Shortcut="n" Help="SourcesCommandNameDescription"/>
-      <SingleValueOption Name="username" Shortcut="u" Help="SourcesCommandUserNameDescription"/>
+      <SingleValueOption Name="username" Shortcut="u" Help="SourcesCommandUsernameDescription"/>
       <SingleValueOption Name="password" Shortcut="p" Help="SourcesCommandPasswordDescription"/>
       <SwitchOption Name="store-Password-In-Clear-Text" Help="SourcesCommandStorePasswordInClearTextDescription"/>
       <SingleValueOption Name="valid-Authentication-Types" Help="SourcesCommandValidAuthenticationTypesDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile" />
+      <Example Title="Add `nuget.org` as a source:" Command="dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org" />
+      <Example Title="Add `c:\packages` as a local source:" Command="dotnet nuget add source c:\packages" />
+      <Example Title="Add a source that needs authentication:" Command="dotnet nuget add source https://someServer/myTeam -n myTeam -u myUsername -p myPassword --store-password-in-clear-text" />
+      <Example Title="Add a source that needs authentication (then go install credential provider):" Command="dotnet nuget add source https://azureartifacts.microsoft.com/myTeam -n myTeam" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
   <Verb Name="disable">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200" 
+       Description="disables an existing source in your NuGet configuration files."
+    >
       <Argument Name="name" Help="SourcesCommandNameDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile"/>
+      <Example Title="Disable a source with name of `mySource`:" Command="dotnet nuget disable source mySource" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
   <Verb Name="enable">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200"
+       Description="enables an existing source in your NuGet configuration files."
+    >
       <Argument Name="name" Help="SourcesCommandNameDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile"/>
+      <Example Title="Enable a source with name of `mySource`:" Command="dotnet nuget enable source mySource" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
   <Verb Name="list">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200"
+       Description="lists all existing sources from your NuGet configuration files."
+    >
       <SingleValueOption Name="format" Help="SourcesCommandFormatDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile"/>
+      <Example Title="List configured sources from the current directory:" Command="dotnet nuget list source" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
   <Verb Name="remove">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200"
+       Description="removes an existing source from your NuGet configuration files."
+    >
       <Argument Name="name" Help="SourcesCommandNameDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile"/>
+      <Example Title="Remove a source with name of `mySource`:" Command="dotnet nuget remove source mySource" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
   <Verb Name="update">
-    <Noun Name="source">
+    <Noun Name="source" Version="3.1.200"
+       Description="updates an existing source in your NuGet configuration files."
+    >
       <Argument Name="name" Help="SourcesCommandNameDescription" />
       <SingleValueOption Name="source" Shortcut="s" Help="SourcesCommandSourceDescription"/>
-      <SingleValueOption Name="username" Shortcut="u" Help="SourcesCommandUserNameDescription"/>
+      <SingleValueOption Name="username" Shortcut="u" Help="SourcesCommandUsernameDescription"/>
       <SingleValueOption Name="password" Shortcut="p" Help="SourcesCommandPasswordDescription"/>
       <SwitchOption Name="store-Password-In-Clear-Text" Help="SourcesCommandStorePasswordInClearTextDescription"/>
       <SingleValueOption Name="valid-Authentication-Types" Help="SourcesCommandValidAuthenticationTypesDescription" />
       <SingleValueOption Name="configfile" Help="Option_ConfigFile" />
+      <Example Title="Update a source with name of `mySource`:" Command="dotnet nuget update source mySource --source c:\packages" />
+      <SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
+      <SeeAlso Title="sources command (nuget.exe)" Url="/nuget/reference/cli-reference/cli-ref-sources" />
     </Noun>
   </Verb>
 </Commands>

src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.cs

@@ -29,7 +29,7 @@ internal static void Register(CommandLineApplication app,
                         CommandOptionType.SingleValue);
                     CommandOption username = SourceCmd.Option(
                         "-u|--username",
-                        Strings.SourcesCommandUserNameDescription,
+                        Strings.SourcesCommandUsernameDescription,
                         CommandOptionType.SingleValue);
                     CommandOption password = SourceCmd.Option(
                         "-p|--password",
@@ -256,7 +256,7 @@ internal static void Register(CommandLineApplication app,
                         CommandOptionType.SingleValue);
                     CommandOption username = SourceCmd.Option(
                         "-u|--username",
-                        Strings.SourcesCommandUserNameDescription,
+                        Strings.SourcesCommandUsernameDescription,
                         CommandOptionType.SingleValue);
                     CommandOption password = SourceCmd.Option(
                         "-p|--password",

src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt

@@ -9,15 +9,27 @@
 <#
     string InitCaps(string input)
     {
+        if (input == null) return null;
+
         string output = input.Substring(0, 1).ToUpper() + input.Substring(1);
         return output;
     }
 
+    bool IsArgumentOrOption(string type)
+    {
+        return IsArgument(type) || IsOption(type);
+    }
+
     bool IsArgument(string type)
     {
         return type == "Argument";
     }
 
+    bool IsOption(string type)
+    {
+        return type == "Option";
+    }
+
     string GetProperty(XElement element)
     {
         switch (element.Name.LocalName)
@@ -26,8 +38,14 @@
                 return "Option";
             case "SwitchOption":
                 return "Option";
+            case "Value":
+                return "Option";
             case "Argument":
                 return "Argument";
+            case "Example":
+                return "Example";
+            case "SeeAlso":
+                return "SeeAlso";
             default:
                 return "Unknown Element Type " + element.Name.LocalName;
         }
@@ -93,28 +111,29 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb","")))
         }
         foreach (XElement option in noun.Descendants())
         {
-            string optionName = option.Attribute(XName.Get("Name", "")).Value;
-            string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value;
-            string optionHelp = option.Attribute(XName.Get("Help", ""))?.Value;
-            string optionFormalName = optionName.Replace("-","");
-
-            if (IsArgument(GetProperty(option)))
+            if (IsArgumentOrOption(GetProperty(option)))
             {
-
+                string optionName = option.Attribute(XName.Get("Name", ""))?.Value;
+                string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value;
+                string optionHelp = option.Attribute(XName.Get("Help", ""))?.Value;
+                string optionFormalName = optionName.Replace("-","");
+                if (IsArgument(GetProperty(option)))
+                {
 #>
                     CommandArgument <#= optionFormalName #> = <#= nounFormalName #>Cmd.Argument(
                         "<#= optionLongName != null ? optionLongName : optionName #>", <#= optionHelp != null ? "Strings."+optionHelp : "" #>);
 <#
-            }
-            else
-            {
-                string optionShortcut = option.Attribute(XName.Get("Shortcut",""))?.Value;
+                }
+                else if (IsOption(GetProperty(option)))
+                {
+                    string optionShortcut = option.Attribute(XName.Get("Shortcut",""))?.Value;
 #>
                     CommandOption <#= optionFormalName #> = <#= nounFormalName #>Cmd.Option(
                         "<#= (optionShortcut != null ? "-" + optionShortcut + "|" : "") + "--" + optionName.ToLower() #>",
                         <#= optionHelp != null ? "Strings."+optionHelp : "" #>,
                         CommandOptionType.<#= GetOptionType(option) #>);
 <#
+                }
             }
         }
 #>
@@ -127,30 +146,34 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb","")))
 <#
         foreach (XElement option in noun.Descendants())
         {
-            string optionName = option.Attribute(XName.Get("Name", "")).Value;
-            string optionFormalName = optionName.Replace("-","");
-            string optionCapsName = InitCaps(optionFormalName);
-            if (IsArgument(GetProperty(option)))
+            if (IsArgumentOrOption(GetProperty(option)))
             {
+                string optionName = option.Attribute(XName.Get("Name", ""))?.Value;
+                string optionFormalName = optionName?.Replace("-","");
+                string optionCapsName = InitCaps(optionFormalName);
+
+                if (IsArgument(GetProperty(option)))
+                {
 #>
                             <#= optionCapsName #> = <#=optionFormalName#>.Value,
 <#
-            }
-            else
-            {
-                string optionType = GetOptionType(option);
-                switch (optionType)
+                }
+                else if (IsOption(GetProperty(option)))
                 {
-                    case "SingleValue":
+                    string optionType = GetOptionType(option);
+                    switch (optionType)
+                    {
+                        case "SingleValue":
 #>
                             <#= optionCapsName #> = <#= optionFormalName #>.Value(),
 <#                    
-                        break;
-                    case "NoValue":
+                            break;
+                        case "NoValue":
 #>
                             <#= optionCapsName #> = <#= optionFormalName #>.HasValue(),
 <#                    
-                        break;
+                            break;
+                    }
                 }
             }
         }
@@ -164,39 +187,41 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb","")))
                 bool required = option2.Attribute(XName.Get("Required", ""))?.Value == "true";
                 if (required)
                 {
-                    string optionName2 = option2.Attribute(XName.Get("Name", "")).Value;
-                    string optionFormalName2 = optionName2.Replace("-","");
-                    string optionCapsName2 = InitCaps(optionFormalName2);
-
-                    if (IsArgument(GetProperty(option2)))
+                    if (IsArgumentOrOption(GetProperty(option2)))
                     {
+                        string optionName2 = option2.Attribute(XName.Get("Name", ""))?.Value;
+                        string optionFormalName2 = optionName2?.Replace("-","");
+                        string optionCapsName2 = InitCaps(optionFormalName2);
+                        if (IsArgument(GetProperty(option2)))
+                        {
 #>
                     if (args.<#= optionCapsName2 #> == null)
                     {
                         throw new CommandException("'<#=optionFormalName2#>' argument is missing but required.");
                     }
 <#
-                    }
-                    else
-                    {
-                        string optionType2 = GetOptionType(option2);
-                        switch (optionType2)
+                        }
+                        else if (IsOption(GetProperty(option2)))
                         {
-                        case "SingleValue":
+                            string optionType2 = GetOptionType(option2);
+                            switch (optionType2)
+                            {
+                            case "SingleValue":
 #>
                         if (args.<#= optionCapsName2 #> == null)
                         {
                             throw new CommandException("'<#=optionFormalName2#>' option is missing but required.");
                         }
 <#                    
-                            break;
-                        case "NoValue":
+                                break;
+                            case "NoValue":
 #>
                         //TODO: implement required for bool
 <#                    
-                            break;
+                                break;
+                            }
                         }
-                    }     
+                    }
                 }
             }
 #>                        <#= commandFormalName #><#= nounFormalName #>Runner.Run(args, getLogger);

src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj

@@ -39,6 +39,7 @@
   </Choose>
 
   <ItemGroup>
+    <Compile Remove="external\*" />
     <Compile Update="Commands\Verbs.cs">
       <DesignTime>True</DesignTime>
       <AutoGen>True</AutoGen>