Update docs contribution guide to include M1 details.

[freakboy3742]

When running on an M1 Mac, there's a couple of extra steps needed to lint documentation.

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]

@rmartin16 Don't suppose you can fill in the gaps here? What's the Windows equivalent of $()?

[proneon267]

Hello
The Windows equivalent is %(). For example, if you wanted to set a variable equal to the output of a command in Windows, you could do: set var=%(command%)

But I think what you are after is:
for /f "usebackq delims=" %i in (`python -m certifi`) do set SSL_CERT_FILE=%i
Also, maybe you can use %%i instead of %i

[rmartin16]

Indeed....cmd uses a FOR loop... to capture command output... 🤷🏼

But usebackq is unnecessary....delims will help avoid breaking the path, though.

FOR /f "delims=" %i IN ('python -m certifi') DO SET SSL_CERT_FILE=%i

That said....this may be a good time to decide if we want to continue providing cmd and powershell commands....or only provide commands compatible with powershell (and subsequently msft's Terminal). According to msft, all windows ship PowerShell now.

This is the PowerShell command:

$env:SSL_CERT_FILE=$(python -m certifi)

Note that neither of these commands can run in the other environment.

CC: @mhsmith incase you have input on providing commands for Windows in docs

[rmartin16]

oh yeah, also....enchant doesn't work with Windows Store Python 🙃

docs-lint: commands[1] C:\Users\user\github\beeware\briefcase\docs> python -m sphinx -W --keep-going -j auto -n -v -E -T -a -d C:\Users\user\github\beeware\briefcase\.tox\docs-lint\tmp/doctrees -b spelling . _build/spell
Running Sphinx v6.1.3

** (python3.10.exe:6932): WARNING **: 08:36:07.767: Error loading plugin: 'C:\Users\user\github\beeware\briefcase\.tox\docs-lint\lib\site-packages\enchant\data\mingw64/lib/enchant-2\enchant_hunspell.dll': The specified module could not be found.

❯ ls C:\Users\user\github\beeware\briefcase\.tox\docs-lint\lib\site-packages\enchant\data\mingw64/lib/enchant-2\enchant_hunspell.dll


    Directory: C:\Users\user\github\beeware\briefcase\.tox\docs-lint\lib\site-packages\enchant\data\mingw64\lib\enchant-2


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         4/11/2023   8:35 AM         632014 enchant_hunspell.dll

[freakboy3742]

Looks like there's a bunch of installation options for penchant... I think I'll just defer to the official docs.

But: Is pyenchant our only option? AFAICT, the only platform where it seems to work well is Linux...

[rmartin16]

and just so its clear....that FOR statement won't run in powershell

[freakboy3742]

Understood. I guess I don't have a good feel for what Windows users consider the "default" shell - or how to signal to Windows users (who are, historically, our users with the least exposure to the command line) that the command is a Powershell command, not a cmd.exe command.

[freakboy3742]

I'm also somewhat hesitant because I thought I'd try out a "beeware tutorial" scenario with Powershell... and the first thing I got was an impenetrable permission error about my execution policy not having permissions to run scripts. I, for one, would rather not put myself in a situation of trying to teach someone who is sending screenshots of terminal sessions how to turn on scripting permissions...

[rmartin16]

I'm not advocating for PowerShell per se; it introduces its own difficulties. It seems that msft is transitioning to a default experience not based on cmd.exe; for instance, they removed it from the Start Menu a while ago. But their approach doesn't seem that heavy-handed, though ( especially when you compare it to how hard they push Edge); so, Windows won't ask me "are you sure you don't want PowerShell even though you typed cmd in the search".

Mostly, I'm just interested in making sure we can provide some level of consistency for documenting commands for Windows. For instance, the Android code-signing page contains commands for both cmd and PowerShell.

[rmartin16]

I know this isn't your point but for completeness...

Open PowerShell with Administrative privileges and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

and restart your terminal sessions.

[rmartin16]

while we're on the topic of windows....tox -e docs-lint believes iOS is spelled wrong on windows