Docs updates

[joerick]

A few little updates and tweaks to docs, to help readability and keep things up-to-date.

[henryiii]

Looks like nice cleanups. :)

[henryiii]

I didn't realize this was scoped like this, nice. :) So it's really only macOS that gets true "global" installs.

[joerick]

Yeah. We could even install the Windows Pythons somewhere nice from appdirs, then maybe we could drop the 'only on CI' warning.

On Mac, I seem to remember that you couldn't install it to a different location for some reason. The installer command supports it, but something in Python wasn't happy.

[YannickJadoul]

Nice, looks great! :-) Seems not a huge update, but I think it's actually a nice sign of the project getting more mature!

Quick thing I noticed: until now, I've been using cibuildweel as stylized version, but so now you're switching to just cibuildweel? (I don't really mind; just thought I'd double check and adapt my habits ;-) )

[joerick]

Quick thing I noticed: until now, I've been using cibuildweel as stylized version, but so now you're switching to just cibuildwheel? (I don't really mind; just thought I'd double check and adapt my habits ;-) )

Yes, good question. Some of the docs entries were getting very backtick heavy, so I decided to remove some of them when they're referring to a project, rather than a command or something the user would type.

Here's what I wrote in the commit message at the time c6ede9b:

Using the backtick too much breaks up the flow of the text and makes it
hard to read. Here, I'm deciding that project names are not backtick'd,
unless they're referring to something the user would type. e.g.

❌ the manylinux project
✅ the manylinux project

❌ set CIBW_MANYLINUX_IMAGE to manylinux2010
✅ set CIBW_MANYLINUX_IMAGE to manylinux2010

Of course, we then hit up the capitalisation problem. All this would read better if we could capitalise the proper nouns. But cibuildwheel doesn't really have a capitalised version that works. Cibuildwheel (eh - Ci?), CIbuildwheel (what), CIBuildWheel (quite ugly IMO). So I'm thinking we stick to lowercase cibuildwheel.

[YannickJadoul]

Yes, good question. Some of the docs entries were getting very backtick heavy, so I decided to remove some of them when they're referring to a project, rather than a command or something the user would type.

That makes sense to me, yes. It might also make other people typing "cibuildwheel" without the backticks more consistent (not sure if that's a good reason, but it's a nice consequence).
I don't really mind, but it's good to know, because I've been doing an effort on having backticks around cibuildwheel, up until now :-)

Here's what I wrote in the commit message at the time c6ede9b:

Right, sorry, didn't see that!

Of course, we then hit up the capitalisation problem. All this would read better if we could capitalise the proper nouns. But cibuildwheel doesn't really have a capitalised version that works. Cibuildwheel (eh - Ci?), CIbuildwheel (what), CIBuildWheel (quite ugly IMO). So I'm thinking we stick to lowercase cibuildwheel.

Also fully agree on those three assessments, yes ;-)

[henryiii]

I'm a mild fan of hard wrapping, though I only manually do it (in vi with Shift+V,G,Q), though I didn't used to be. It makes the diffs easier to read, as small one change in a line becomes much harder to spot if that lines is wider than your screen / diff view in GitHub. Large changes "reflow" the whole paragraph, but that's not any worse than the unreadable one-line diff if it's all on a single line. You don't have to be perfect about it, though, I only reflow when it starts looking bad.

Also fully agree on those three assessments

I would only add that it then should be "Cibuildwheel" at the beginning of a sentence. Which I probably have been doing once in a while anyway.

[joerick]

Travis failure unrelated, ofc.