-
-
Notifications
You must be signed in to change notification settings - Fork 375
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.
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
Docs: Add Building a CLI Application Tutorial #1958
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/how-to/cli-apps.rst
Outdated
Next steps | ||
---------- | ||
|
||
So far we have been running the application in developer mode. To distribute the application, you will need to package it for distribution. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sure, I will add the packaging steps
Co-authored-by: Russell Keith-Magee <[email protected]>
Just to confirm - is this ready for another review, or are you expecting to make more updates? |
Not yet, the packaging steps are still not done, when it's done I will re-request your review. |
fix #1947
PR Checklist: