From 571fa0c200c62c09b33f1cfc7df09814537b50d9 Mon Sep 17 00:00:00 2001 From: Akshita Date: Mon, 3 Jun 2019 14:26:34 -0700 Subject: [PATCH 1/8] Add the xml comments --- .../Tutorial/content/Program.cs | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs index de81332fc..d89ab661d 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs @@ -3,13 +3,17 @@ namespace Microsoft.DotNet.Try.ProjectTemplate.Tutorial { - ///Takes in the --region option from the code fence options in markdown - ///Takes in the --session option from the code fence options in markdown - ///Takes in the --package option from the code fence options in markdown - ///Takes in the --project option from the code fence options in markdown - ///Takes in any additional arguments passed in the code fence options in markdown + ///This program uses System.CommandLine DragonFruit to accept arguments from command line. + ///Execute: dotnet run --region "HelloWorld" to see the output + /// public class Program { + ///Takes in the --region option from the code fence options in markdown + ///Takes in the --session option from the code fence options in markdown + ///Takes in the --package option from the code fence options in markdown + ///Takes in the --project option from the code fence options in markdown + ///Takes in any additional arguments passed in the code fence options in markdown + ///To learn more see our documentation static int Main( string region = null, string session = null, @@ -25,7 +29,7 @@ static int Main( }; } - public static int HelloWorld() + internal static int HelloWorld() { #region HelloWorld Console.WriteLine("Hello World!"); @@ -33,7 +37,7 @@ public static int HelloWorld() return 0; } - public static int DateTime() + internal static int DateTime() { #region DateTime Console.WriteLine(System.DateTime.Now); @@ -41,9 +45,10 @@ public static int DateTime() return 0; } - public static int EmptyRegion() + internal static int EmptyRegion() { #region EmptyRegion + Console.WriteLine(@"No region was specified at the command line. Try specifying ""DateTime"" or ""HelloWorld"" region"); #endregion return 0; } From a0cb00af76ad557cb2aa6000197c954340a04dc4 Mon Sep 17 00:00:00 2001 From: Akshita Date: Mon, 3 Jun 2019 14:53:52 -0700 Subject: [PATCH 2/8] dont use empty region --- .../Tutorial/content/Program.cs | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs index d89ab661d..03f73e844 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs @@ -23,10 +23,10 @@ static int Main( { return region switch { - "HelloWorld" => HelloWorld(), - "DateTime" => DateTime(), - _ => EmptyRegion() - }; + "HelloWorld" => HelloWorld(), + "DateTime" => DateTime(), + _ => throw new ArgumentException("A --region argument must be passed", "region") + }; } internal static int HelloWorld() @@ -44,13 +44,5 @@ internal static int DateTime() #endregion return 0; } - - internal static int EmptyRegion() - { - #region EmptyRegion - Console.WriteLine(@"No region was specified at the command line. Try specifying ""DateTime"" or ""HelloWorld"" region"); - #endregion - return 0; - } } } \ No newline at end of file From 76e615cb8faba024dbfd68214910e1e7d1e61855 Mon Sep 17 00:00:00 2001 From: Akshita Date: Mon, 3 Jun 2019 14:54:46 -0700 Subject: [PATCH 3/8] use nameof --- .../Tutorial/content/Program.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs index 03f73e844..5eb1944a5 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs @@ -25,7 +25,7 @@ static int Main( { "HelloWorld" => HelloWorld(), "DateTime" => DateTime(), - _ => throw new ArgumentException("A --region argument must be passed", "region") + _ => throw new ArgumentException("A --region argument must be passed", nameof(region)) }; } From d74821a3bee5c22ceedd15307e38c37be243bc7b Mon Sep 17 00:00:00 2001 From: Akshita Date: Tue, 4 Jun 2019 18:37:50 -0700 Subject: [PATCH 4/8] add some changes --- .../Tutorial/content/Program.cs | 2 +- .../Tutorial/content/Readme.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs index 5eb1944a5..02a8c99c1 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs @@ -3,7 +3,7 @@ namespace Microsoft.DotNet.Try.ProjectTemplate.Tutorial { - ///This program uses System.CommandLine DragonFruit to accept arguments from command line. + ///This program uses System.CommandLine.DragonFruit to accept command line arguments from command line. ///Execute: dotnet run --region "HelloWorld" to see the output /// public class Program diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md index 99c7e5780..1e5f8767b 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md @@ -26,12 +26,12 @@ This should launch a browser window. The following code fence will be replaced b ## What's happening behind the scenes -Code fences are a standard way to include code in your markdown files. The only change you need to do is to add few options in the first line of your code snippet. If you notice the above code snippet, there are three options in action. +Code fences are a standard way to include code in your markdown files. The only change you need to make is to add few options in the first line of your code snippet. If you notice the above code snippet, there are three options in use. | Option | What it does | |----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | `--project ./Microsoft.DotNet.Try.ProjectTemplate.Tutorial.csproj` | Points to the project that the sample is part of. (Optional. Defaults to any .csproj in the same folder as the `.md` file.) | -| `--region HelloWorld` | Identifes a C# code `#region` to focus on. (Optional. If not specified, the whole file is displayed in the editor.) | +| `--region HelloWorld` | Identifies a C# code `#region` to focus on. (Optional. If not specified, the whole file is displayed in the editor.) | | `--source-file ./Program.cs` | Points to the file where the sample code is pulled from. If you navigate back to Program.cs you will be able to see the various regions and the context in which your code is being execute. As an exercise, try to change the region in the previous code snippet to `DateTime` and then refresh the browser. You should be able to see the text that is a part of the `DateTime` region now. From 5443014ce19a85f2f1a66aa18ef74e1114063a0e Mon Sep 17 00:00:00 2001 From: Akshita Date: Wed, 5 Jun 2019 11:35:07 -0700 Subject: [PATCH 5/8] refine a bit --- .../Tutorial/content/Readme.md | 23 ++----------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md index 1e5f8767b..115d5ee37 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md @@ -1,25 +1,6 @@ # Creating interactive documentation with Try .NET -## Setup -Before getting started with the sample above, you need to install the `dotnet try` global tool. In a terminal execute - -```console -dotnet tool install --global dotnet-try -``` - -Once installed you can execute -```console -dotnet try -h -``` -and see the list of available commands. - -## Executing your first sample - -In the directory of the project execute -```console -dotnet try -``` -This should launch a browser window. The following code fence will be replaced by the editor and you can execute the code by hitting the run button. +## This code fence will run the HelloWorld method from Program.cs ```cs --source-file ./Program.cs --project ./Microsoft.DotNet.Try.ProjectTemplate.Tutorial.csproj --region HelloWorld ``` @@ -38,7 +19,7 @@ If you navigate back to Program.cs you will be able to see the various regions a ## Learn More -The above are the basic to get you started with creating your own interactive documentation. To learn more about the `dotnet try` features, at the command line execute +To learn more about the `dotnet try` features, at the command line execute ```console dotnet try demo From 6412d8c3c001053e8a823596b3a5e53086a0ca59 Mon Sep 17 00:00:00 2001 From: Akshita Date: Thu, 6 Jun 2019 14:35:32 -0700 Subject: [PATCH 6/8] Make the readme more concise --- .../Tutorial/content/Readme.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md index 115d5ee37..10e847e5f 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Readme.md @@ -1,32 +1,20 @@ # Creating interactive documentation with Try .NET +## Setup +If you haven't installed the `dotnet try` global tool, you can install it by following the instructions [here](https://github.com/dotnet/try#setup). + ## This code fence will run the HelloWorld method from Program.cs ```cs --source-file ./Program.cs --project ./Microsoft.DotNet.Try.ProjectTemplate.Tutorial.csproj --region HelloWorld ``` -## What's happening behind the scenes - -Code fences are a standard way to include code in your markdown files. The only change you need to make is to add few options in the first line of your code snippet. If you notice the above code snippet, there are three options in use. - -| Option | What it does | -|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| `--project ./Microsoft.DotNet.Try.ProjectTemplate.Tutorial.csproj` | Points to the project that the sample is part of. (Optional. Defaults to any .csproj in the same folder as the `.md` file.) | -| `--region HelloWorld` | Identifies a C# code `#region` to focus on. (Optional. If not specified, the whole file is displayed in the editor.) | -| `--source-file ./Program.cs` | Points to the file where the sample code is pulled from. - -If you navigate back to Program.cs you will be able to see the various regions and the context in which your code is being execute. As an exercise, try to change the region in the previous code snippet to `DateTime` and then refresh the browser. You should be able to see the text that is a part of the `DateTime` region now. - ## Learn More - To learn more about the `dotnet try` features, at the command line execute ```console dotnet try demo ``` -This interactive demo will walk you through the various features in `dotnet try`. - ## Feedback We love to hear from you. If you have any suggestions or feedback please reach out to us on [GitHub](https://github.com/dotnet/try) From df13dea3409c816aa6d84fe44f562eaf16d8c141 Mon Sep 17 00:00:00 2001 From: Akshita Date: Thu, 6 Jun 2019 15:26:06 -0700 Subject: [PATCH 7/8] fix formatting --- .../Tutorial/content/Program.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs index 02a8c99c1..57610339f 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate/Tutorial/content/Program.cs @@ -23,10 +23,10 @@ static int Main( { return region switch { - "HelloWorld" => HelloWorld(), - "DateTime" => DateTime(), - _ => throw new ArgumentException("A --region argument must be passed", nameof(region)) - }; + "HelloWorld" => HelloWorld(), + "DateTime" => DateTime(), + _ => throw new ArgumentException("A --region argument must be passed", nameof(region)) + }; } internal static int HelloWorld() From e2bec7981a93f783bab8b0612397bf89452abf68 Mon Sep 17 00:00:00 2001 From: Akshita Date: Thu, 6 Jun 2019 16:58:05 -0700 Subject: [PATCH 8/8] The test pass --- .../TutorialTemplateTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Microsoft.DotNet.Try.ProjectTemplate.Tests/TutorialTemplateTests.cs b/Microsoft.DotNet.Try.ProjectTemplate.Tests/TutorialTemplateTests.cs index c47e64762..c873ec6b8 100644 --- a/Microsoft.DotNet.Try.ProjectTemplate.Tests/TutorialTemplateTests.cs +++ b/Microsoft.DotNet.Try.ProjectTemplate.Tests/TutorialTemplateTests.cs @@ -57,7 +57,7 @@ public async Task When_the_template_is_installed_verify_works() .Trim() .Should() .Match( - $"{outputDirectory}{Path.DirectorySeparatorChar}Readme.md*Line 24:*{outputDirectory}{Path.DirectorySeparatorChar}Program.cs (in project {outputDirectory}{Path.DirectorySeparatorChar}{outputDirectory.Name}.csproj)*".EnforceLF()); + $"{outputDirectory}{Path.DirectorySeparatorChar}Readme.md*Line *:*{outputDirectory}{Path.DirectorySeparatorChar}Program.cs (in project {outputDirectory}{Path.DirectorySeparatorChar}{outputDirectory.Name}.csproj)*".EnforceLF()); resultCode.Should().Be(0);