Mistakes / lack of clarity in the tutorial

[shalgrim]

What kind of documentation issue is this?

Unclear or confusing documentation

Affected page

https://tutorial.beeware.org/tutorial/tutorial-3/

Describe the issue

I actually have four small issues on various pages, but on Discord @kattni suggested I make a single issue.

One

On step 3:

Once this completes, if you look in the project directory, you should now see a directory corresponding to your platform (macOS, linux, or windows)

It could be more clear that that directory shows up within the build directory. Later on, when the .dmg gets created it points out it's in the dist directory, so I think the platform folder being in build could be more explicit

Two

On step 7,

essentially any package on PyPI package can be installed

should probably be

essentially any package on PyPI can be installed

Three

On step 8, it says the change in say_hello will cause the API to obtain post 42, which is probably a reference to an older version of the tutorial as we're now just going straight to a json object

Four

Also on step 8, and this is the most complex one.

There's a confusing bit:

Briefcase uses httpx internally, so it's already in your local environment - you don't need to install it separately to use it here. Let's add a httpx API call to our app. Modify the requires setting in our pyproject.toml to include the new requirement:

So if it's already there, why do we have to add it? I think I figured out that it's only in the dev environment, but the first time through I bumped on this and was confused.

Later it says

we need to tell developer mode to reinstall requirements, by using the -r argument:

And based on my run through, it's not necessary there. It is necessary on the briefcase run step

Suggested improvement

I'll follow this up with a PR with my suggestions in it

[freakboy3742]

Thanks for the report. Completely agreed on all these problems; some context if it's helpful:

1. Once upon a time, Briefcase did generated into a macOS, or linux or windows directory; a couple of years ago, we moved all those into a single build subdirectory. Looks like you've found a subtle reference to the old layout that has been missed in multiple re-reads.
2. The Department of Redundancy Department will be in contact shortly :-)
3. Your suspicion is correct - we changed this less than a week ago (Fix JSON API usage, and link to main EN translation. #65). We had to rush this fix because of an upstream change that prevented completing the tutorial (Sample API currently flagged for phishing #64), and this reference was evidently missed.
4. This is also the result of a recent change. Prior to Briefcase 0.4, development dependencies were installed into the same environment that Briefcase was installed into. Briefcase 0.4 (released last week) changed this so that apps have a standalone development environment. This was reflected in the tutorial in Modify tutorial to reflect isolated development mode. #44; but evidently we've missed some references (as well as a reference to the {JSON} Placeholder API in the same paragraph.

The intended behaviour for 3 and 4 is:

1. The fact that httpx is a dependency of Briefcase is of no significance any more, and shouldn't be mentioned
2. The first step as a user is to add httpx to your app, and run briefcase dev -r. Dependencies will only be installed by default when a venv for a specific app hasn't been created before, or if the version of python being used to run Briefcase changes. If you changed Briefcase virtual environment (and thus python version?), or deleted the .briefcase folder between step 7 and 8 - that would explain the fact that you didn't need -r.
3. We're hitting "a URL that returns JSON", not "post 42 of the {JSON} Placeholder API.
4. As you've noted, you'll also need -r when you briefcase run the updated app.

[shalgrim]

Thanks @freakboy3742. I've got a non-urgent PR to address this issue ready for review.

If you changed Briefcase virtual environment (and thus python version?), or deleted the .briefcase folder between step 7 and 8 - that would explain the fact that you didn't need -r.

I didn't do either of those things and still didn't need -r (or even to add httpx to pyproject.toml) when running briefcase dev . My read was that it was because httpx, since it's used internally by briefcase, is already installed in the local (i.e., dev) environment. This is reflected in the PR, but let me know if I'm mistaken.

[freakboy3742]

Thanks @freakboy3742. I've got a non-urgent PR to address this issue ready for review.

👍 Thanks - I'll review that shortly.

I didn't do either of those things and still didn't need -r (or even to add httpx to pyproject.toml) when running briefcase dev . My read was that it was because httpx, since it's used internally by briefcase, is already installed in the local (i.e., dev) environment. This is reflected in the PR, but let me know if I'm mistaken.

What version of Briefcase are you running? If you started the tutorial before Thursday last week, you might be on Briefcase 0.3.26 rather than 0.4.0, which would explain the discrepancy - that's when the isolated environment change was introduced.

[shalgrim]

Briefcase version is 0.4.1

[freakboy3742]

This is really weird - I've just run through the tutorial (skipping steps 5 and 6, as they don't use dev mode), and I can't reproduce what you're seeing.

If I follow the tutorial text, I get the faker ModuleNotFoundError in tutorial 7 with briefcase dev; then I run briefcase dev -r to fix it. Then I add httpx to the requires list; if I run briefcase dev at this point, I get a ModuleNotFoundError for httpx, which is what I'd expect if I was using Briefcase 0.4.1.

Can I ask you to:

1. Create and activate a new virtual env, and python -m pip install briefcase
2. Show the output of python -m pip freeze | grep briefcase
3. Create a new temp directory, and run briefcase new, accepting all defaults
4. Run briefcase dev --log, and provide the log file
5. Run tutorial 7, adding faker, and running briefcase dev -r --log, and provide the log file
6. Start tutorial 8, adding httpx, and running briefcase dev --log, and provide the log file

[shalgrim]

Yeah, running through the tutorial again with a fresh environment was going to be my suggestion, too. I'll do that and follow the steps you have above, too

[shalgrim]

I suspected this might happen. I cannot repro the behavior I observed or think I observed before. Which is good news, I think, despite having wasted some of our time.

I'll adjust the PR accordingly.

[freakboy3742]

(waves fist at computer)!!!!

Agreed it would be nice to know exactly how you got the behavior you were describing, though. Thanks for going on the journey :-)