Docs: Add Building a CLI Application Tutorial

[john0isaac]

fix #1947

PR Checklist:

• [-] All new features have been tested
• [-] All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[freakboy3742]

Thanks - this is a good first draft. The underlying example is a good target, and you've covered most of the major points that we need to hit.

The major issue that needs to be resolved is whether this should be a tutorial or a HOWTO. I suspect that you've landed on writing this as a HOWTO because of the existing language in the tutorials section leading to the HOWTO page - but that should be read more of an indication that we need to lay a path to somewhere, and in the absence of more tutorial pages, HOWTOs are the next step.

We use diataxis as a guide for how we structure our docs. In that framework, a tutorial is a complete step-by-step guide, coming from a clean starting point (or at least a known starting point). It's a learning guide, aiding knowledge acquisition. A HOWTO guide, on the other hand, is focused on achieving a specific task. It can assume some background knowledge about how the tool works. It's a more practical guide to completing a specific task. Generally, a HOWTO will be a lot shorter, as it will point out the major steps and landmarks, but won't hold your hand the whole way.

A HOWTO for building a CLI would be really short. It wouldn't need to be much more than a bunch of bullet points highlighting the major differences between a GUI and CLI app built with Briefcase.

Therefore, I think I'd lean towards the tutorial in this case. If you've already got a good handle on how Briefcase works, then the process of building a CLI tool shouldn't be that unexpected. The only thing that you might not already know about is the handling of command line arguments, and how the app will appear on the command line.

However, even in a tutorial, we can lean heavily on assuming the user has done the existing BeeWare tutorial. I'd suggest structuring this document as the first of a collection of "additional tutorial topics" - similar to how the end of the BeeWare tutorial is structured. Those tutorials assume you've already done the main tutorial (and explicitly say as much), but build on that knowledge with a new example.

In that context, you don't need to be explicit about all the initial setup steps - you should definitely summarise the main steps (create a fresh venv, install Briefcase, create an app with a name of hello-cli, select Console as the GUI framework); but that's more by way of refreshing the user's memory about the steps required, not explicit handholding. You can defer to "as you did in step X of the beeware tutorial"-style instructions, rather than giving full explicit console output of every step. You only need to be explicit when something new is happening - for example, in the packaging step, showing how the installed app would be executed.

I've left a few other comments inline; if you need any clarification on any of this, I'm happy to fill in the gaps.

[freakboy3742]

I'm not sure we can leave this one out. One of the major questions for CLIs is "how will this work for users" - in particular, how this manifests on the command line.

If we pick a name like hello-cli, that also gives us the opportunity to do a quick discussion of PEP508 naming, because hello-cli is a valid app name, but won't be a valid module name, so the code will be in a hello_cli/app.py.

[john0isaac]

sure, I will add the packaging steps

[freakboy3742]

Just to confirm - is this ready for another review, or are you expecting to make more updates?

[john0isaac]

Not yet, the packaging steps are still not done, when it's done I will re-request your review.
I will do it in the next couple of hours.
Thanks for checking.