Samples, quickstart, and interactive documentation

[jonsequitur]

Interactive documentation (under the /samples/tutorial directory) needs to be expanded upon and improved. When Try .NET adds support for publishing static Markdown files based on interactive tutorials (dotnet/try#214), this documentation can also become the basis for the wiki and other online documentation.

Topics for which improved documentation would be useful include the following. (I've included links to existing wiki content but most of these topics can be expanded upon.)

• Parser configuration and parsing
  • Concepts: Syntax, delimiters, types of symbols, aliases, arity, etc.
  • Directives
  • Using the ParseResult
  • Help
• Suggestions
  -[ ] dotnet-suggest
• Parse preview via the [parse] directive
• Model binding
• Middleware pipeline
• DragonFruit
• System.CommandLine.Rendering
  • Output modes
  • Rendering directives ([enable-vt], [output])
• Debugging using the [debug] directive
• Cancellation handling
• Generic host integration

[seanalford]

@jonsequitur what sort of samples/quick-starts are looking for? I've been working on a Console (.NET Core) template that provides a dependency injection container, application settings, and logging out of the box. In addition to processing the command line arguments, I'm also planning to utilize the command-line-api as a runtime command processor. I'd be happy to share this template, and provide some simpler examples if you'd be interested.

[jonsequitur]

This sounds like an interesting example and I'd love to see it. Any overlap with #533?

Given how sparse our documentation is at this point, the thing that will be most valuable first is low-level API samples. I created one using Try .NET which is under /samples/tutorial and that would be a great place to build from.

[seanalford]

@jonsequitur thanks! I wasn't aware of #533, and yes there is some over-lap. I've reached out to @couven92 for suggestions. I'll get back once I have something more polished.

[fredrikhr]

Maybe I should add back the small hosting sample I orignally had in #533?

master...couven92:hosting-sample

it should also work together with dotnet try, right?

@jonsequitur

[jonsequitur]

Can the sample be packaged up as a dotnet try-enabled doc under /samples/tutorials? In particular, a working example of the the cancellation handling would be useful.

[fredrikhr]

@jonsequitur I can try :)