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.

Sign up for GitHub

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

Generate docs for dotnet nuget commands. #3253

Merged
merged 17 commits into from
Apr 8, 2020
Merged

Generate docs for dotnet nuget commands. #3253

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
6955d1c
Generate docs for dotnet nuget commands.
Feb 21, 2020
355fd9c
Fix links to docs to be non-locale specific.
Feb 21, 2020
d467312
for nuget, we are supposed to use relative uris, since they are used …
Feb 21, 2020
9bba5e1
always run ttGen.ps1 when editing commands.xml or any .tt file.
Feb 21, 2020
86a02ab
fix feedback in PR and offline with sdk docs lead
Feb 28, 2020
62c0c45
lowercase all option string
Feb 28, 2020
fd3ecdf
Provide file name and path info in concatenated file.
Mar 2, 2020
38f17a4
PR Feedback fixes (UserName -> Username, etc...)
Mar 6, 2020
03ebc2f
more instructions on scripts. change location of scripts.
Mar 9, 2020
6cfb7c2
make encoding UTF8 so unicode check mark gets output. remove double b…
Mar 9, 2020
cb74f3b
create file with ASCII (still have to handle unicode better)
Mar 9, 2020
4b67309
Fixes in order to improve formatting based on docs team feedback.
Mar 9, 2020
09b239b
per docs PR feedback - alphabetize options and fix validauthenticatio…
Mar 20, 2020
a2b2824
improve validauthtypes docs per docs team feedback
Mar 25, 2020
9b4377b
PR feedback
Mar 31, 2020
4ba98b3
update URLs for examples to use more contoso
Mar 31, 2020
9f63944
don't do 1 line if statement
Mar 31, 2020
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
10 changes: 10 additions & 0 deletions build/ttGen.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Write-Host "Regenerating all generated files from all .tt files."
rrelyea marked this conversation as resolved.
Show resolved Hide resolved
$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"
}
}
11 changes: 11 additions & 0 deletions src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@
return type == "Argument";
}

bool IsOption(string type)
{
return type == "Option";
}

string GetProperty(XElement element)
{
switch (element.Name.LocalName)
Expand All @@ -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;
}
Expand Down
45 changes: 39 additions & 6 deletions src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
>
rrelyea marked this conversation as resolved.
Show resolved Hide resolved
<Argument Name="Source" LongName="PackageSourcePath" Help="SourcesCommandSourceDescription" />
<SingleValueOption Name="name" Shortcut="n" Help="SourcesCommandNameDescription"/>
<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" />
rrelyea marked this conversation as resolved.
Show resolved Hide resolved
<SeeAlso Title="Package source sections in NuGet.config files" Url="/nuget/reference/nuget-config-file#package-source-sections" />
zivkan marked this conversation as resolved.
Show resolved Hide resolved
<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="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="Enable 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>
</Commands>
103 changes: 64 additions & 39 deletions src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,27 @@
<#
string InitCaps(string input)
{
if (input == null) return null;
rrelyea marked this conversation as resolved.
Show resolved Hide resolved

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)
Expand All @@ -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;
}
Expand Down Expand Up @@ -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) #>);
<#
}
}
}
#>
Expand All @@ -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;
}
}
}
}
Expand All @@ -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);
Expand Down
1 change: 1 addition & 0 deletions src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
</Choose>

<ItemGroup>
<Compile Remove="external\*" />
<Compile Update="Commands\Verbs.cs">
<DesignTime>True</DesignTime>
<AutoGen>True</AutoGen>
Expand Down
Loading