docs: provide a more gentle introduction to applets

[jwise]

I had some confusion in the Glasgow real-time chat channels recently around when it would be appropriate to write an applet vs. to write a subcommand; subsequently, I had more confusion when I was reading the source code around how applets were defined. This pull request shores up the documentation in a few ways:

• Adjusts the getting started guide to now read as a suggested flow -- both a flow for first steps in using the device, and a suggested conceptual flow to understand applets (where they come from, and how they can be used).
• Tweaks usage to always refer to the command line tool as glasgow, but the hardware or environment as "Glasgow".
• Reorganizes the documentation to make the "applet" the central concept.
• Adds a link to how applets are enumerated, for silly people who are just reading the source and docs from a browser on a phone and not actually running glasgow run --help :-)

I've tried to keep this within the voice already used by Glasgow, and in the documentation style guidelines, but my documentation voice is also kind of opinionated. In particular, I didn't really get a good sense for what voice the documentation preferred to use to describe itself; I half-heartedly used "we" and "you" rather than "the documentation" and "the user" because it seems friendlier (and because I am used to using the royal "we" in documentation), though I note also that the REPL page uses "I". If you have other suggestions to homogenize the documentation voice I am happy to make those changes.

Feel free to request changes, provide nits or general comments, make changes on your own without my involvement, or even just shrug if you don't have time to think too hard about this right now!

[whitequark]

• Adjusts the getting started guide to now read as a suggested flow -- both a flow for first steps in using the device, and a suggested conceptual flow to understand applets (where they come from, and how they can be used).

This is great!

• Tweaks usage to always refer to the command line tool as glasgow, but the hardware or environment as "Glasgow".
• Reorganizes the documentation to make the "applet" the central concept.

This is excellent.

I've tried to keep this within the voice already used by Glasgow, and in the documentation style guidelines, but my documentation voice is also kind of opinionated. In particular, I didn't really get a good sense for what voice the documentation preferred to use to describe itself; I half-heartedly used "we" and "you" rather than "the documentation" and "the user" because it seems friendlier (and because I am used to using the royal "we" in documentation), though I note also that the REPL page uses "I". If you have other suggestions to homogenize the documentation voice I am happy to make those changes.

This is very much welcome and I'm going to think a bit more about it.

For context, the current doc was written by two people: I wrote most of it, Attie wrote the "basic" section with me doing a shallow editing pass. I know that it's much more inconsistent than my usual docs and making it use a consistent voice is something I wanted for a while. I don't know what to do here offhand but we should work something out here.

• Adds a link to how applets are enumerated, for silly people who are just reading the source and docs from a browser on a phone and not actually running glasgow run --help :-)

(Github on a phone sounds kind of miserable.) I think we could address this in two ways:

1. There is a way to integrate argparse with sphinx. We could export all of the options and help text from argparse as sphinx pages you can browse with your phone or something. This is, I think, preferred.
2. We could say that all (upstream) applets live in software/glasgow/applet/**/__init__.py which should also cover your use case without creating additional support burden for me in form of people expecting OOT applets to work.

[jwise]

I think the broader comment I have about the target user of Glasgow is that it is not obvious to me that "a user that can compose complex command lines, but cannot compose simple Python statements" is a user that exists anymore in 2024 (for better, or for worse). That is to say, if the baseline documentation for Glasgow firmly avoids even addressing the possibility that a Glasgow user might be a developer, I think that it might actually be less useful for the median Glasgow user. My strong suspicion is that the median Glasgow user will probably invoke the Glasgow REPL a nonzero number of times, and so it probably is important to assume that "working under the hood" is at least somewhat part of the Glasgow experience.

(Part of this is because I suspect that a user who wants to do just one thing will probably buy just one device these days! If a user wants to only program SPI flash, then they will buy a SPI flash programmer; if they want only to interact with a UART, they will buy some hellish ch341 device, etc.)

[whitequark]

I think the broader comment I have about the target user of Glasgow is that it is not obvious to me that "a user that can compose complex command lines, but cannot compose simple Python statements" is a user that exists anymore in 2024 (for better, or for worse).

Oh, I expect virtually everyone to start using the REPL sooner or later. It's not Python programming experience that I don't want to assume, but software engineering experience, which is all the ancillary stuff (packaging, Python tooling and its metadata, how to version control changes, how to track the upstream, that you must expect the upstream to break your code, et cetera) around it that most people who can program in Python don't have. You'll see this expressed in the introduction and installation sections: we emphasize the Python bit, and then heavily invest into tooling that lets you work without having to deal with the software engineering problems. Sure, it helps professional Python developers too, but that's a secondary utility.

OOT applets are the bane of my existence and the absolute peak of software engineering problems here: there's no clearly defined API, no metholodology for writing tests, no clear support criteria, not even instructions for co-installing your OOT applets into the pipx environment (which by the way is a pretty cursed thing to do because they compound the combinational explosion of versioning and make it a lot more annoying to just kill and reinstall the venv if something goes wrong). I do not wish to commit to supporting them anytime in the near future. At least if you put them in your own fork they mostly stay your own problem instead of becoming everyone's and most of all mine.

[jwise]

(The following are comments that I wanted to write down somewhere but I don't think are blocking my understanding of this PR, nor are they things that I think are material to be addressed in this PR. They are just things that I wanted to get out of my brain.)

Oh, I expect virtually everyone to start using the REPL sooner or later. It's not Python programming experience that I don't want to assume, but software engineering experience [...]. Sure, it helps professional Python developers too, but that's a secondary utility.

That's fair. I think that my current reading of the docs are such that the expectation is that a user may not know how to use a command line effectively, and may not know what a REPL is. The expectation that you describe here is more in line with my anticipation of what an ordinary Glasgow user woudl be.

OOT applets are the bane of my existence...

You mentioned to me also that a potentially preferable approach is to write a script that directly imports Glasgow Python bits. I think this makes a lot of sense. Indeed, there is nothing that you can do in an applet that you cannot do in a standalone script -- and then you can either set your own dependencies, or have a #yolo script hanging around your disk (which, Everybody Knows, is supposed to break if you look at it funny).

I wonder if the documentation at some point should describe that there is another "view" of Glasgow that is not through the glasgow tool, or through the lens of applets, and that if you think you want to write an OoT applet, then you probably want to write a script that uses the Glasgow libraries, or something.

One problem is that all I hear is that OoT applets are the thing not to do, because it is In The Future And Anyway Kinda Sucks And Definitely Not For Today, and I had never considered that there is another thing to do that you actually can do today, that is probably better than OoT applets ever will be. So maybe the play is simply to document that -- as an aside around interacting with applets, and in the applet developer documentation.

[whitequark]

That's fair. I think that my current reading of the docs are such that the expectation is that a user may not know how to use a command line effectively, and may not know what a REPL is. The expectation that you describe here is more in line with my anticipation of what an ordinary Glasgow user woudl be.

I do think we should have a section on how to use the REPL, maybe even in the instructions for basic use!

I wonder if the documentation at some point should describe that there is another "view" of Glasgow that is not through the glasgow tool, or through the lens of applets, and that if you think you want to write an OoT applet, then you probably want to write a script that uses the Glasgow libraries, or something.

I also don't want to support that use, for the same reason: there is no stable API and no API documentation and I actively do not want to have it documented until the API is more stable. I feel so strongly about this that if you put my back against the wall I would archive the project.

One problem is that all I hear is that OoT applets are the thing not to do, because it is In The Future And Anyway Kinda Sucks And Definitely Not For Today, and I had never considered that there is another thing to do that you actually can do today, that is probably better than OoT applets ever will be.

They are literally the same thing with the same core problem: there is no contract, so the contract becomes "whatever the most abusive user who can still skirt under the hard line for moderation can coerce me into supporting". The only difference between an OOT applet and importing bits of the framework manually is that one of those is callable from the CLI and the other is not.

The sole bit of machinery that is involved in OOT applets is the discovery of the applet class. It's not doing anything else.

The reason I push back against OOT applets is because having them exposed in the CLI makes it look like you should publish a collection of them. But the same applies to a collection of useful scripts.

[jwise]

Fair enough. Should the "may support" text in the footnote go away, then?

[whitequark]

Should the "may support" text in the footnote go away, then?

No, it's fine: we eventually will get a stable API, hopefully not too far from now even, now that Amaranth makes it possible. But I want this to happen on my terms and not on someone else's.

[whitequark]

(For onlookers reading my responses above, my feelings towards OSS maintenance are informed, in this case, mainly by my experience with the SolveSpace project and a user going by Symbian9. I am extremely unwilling to repeat that experience.)