docs: use GitHub example in readme

[henryiii]

Swapping the readme example with GHA. Should we do deploy (properly) in the readme? I would rather think not, since it will make it a bit longer if we do it properly (cleaner and more modular). I've also approximately changed the Travis CI example to the correct deployment scheme. I didn't add mention of the trick I have to use to stop it from adding the SDist (important if you combine GHA + Travis for ARM, for example). Hopefully this is at least a starting point.

[YannickJadoul]

Last call for @joerick, ofc, since he originally added the deployment version here, but I'm happy just referring to it and keeping it short :-)

[Czaki]

I think that it should be nice to shou usage of environment variables in examples. Maybe something with CIBW_BUILD or CIBW_SKIP?

[joerick]

for the option, how about:

        env:
          # add options here, for example,
          # CIBW_SKIP: "cp27-*" # Skip building CPython 2.7 on all platforms

[joerick]

There's a typo here, it should be 27, not 25. But also I don't think the setting should be written in the config like this, as users might assume that it's required for this setup to work. Also skipping 2.7 would also mandate the removal of the choco install in windows. If the line is there but commented, users can assume it's educational, not required.

[henryiii]

Oops. How about:

Suggested change

	CIBW_SKIP: "?p25-*" # Skip building Python 2.7 wheels on all platforms
	CIBW_SKIP: "?p27-*" # Skipping Python 2.7 for this example. See docs and examples for details on Python 2.7.

This has several benefits:

1. It avoids having to show choco install, which is very verbose for a simple readme example and is wrong for a large portion of Python 2.7 users, since it doesn't support anything above C++03 (so no pybind11, etc).
2. cibuildhwheel will need to support Python 2 as long as the manylinux wheels have it, but we don't have to include it in the "simplest possible" example in the readme. It's already been tripping up users like in Ideas for improving the first-run experience #468
3. It can remain in the bigger example in the examples folder.

I'd hope most users are past 2.7 support, so this is the new "default", with <50% now needing the Python 2 part, making an example that skips it more useful for a minimal first example. I'll restore it if you want it back, though.

[YannickJadoul]

Do we really want to do this? I thought the idea was that for this example to be as minimal/general as possible?

[Czaki]

As I see our general example does not show how to use config variables. Also, we got bug reports like #468. I`m ok with disabling python 2.7 in the initial configuration from readme and does not do this in the example yaml file.

[henryiii]

Dropping 2.7 via a variable is more minimal than adding a whole step that adds Python 2.7 but only works for C/C++<11. And does removing 2.7 from the readme example really make it less general at the end of 2020? If anything it still shows that we support it (since we remove it via a variable), and highlights that there are caveats to using it (the extra step or steps for C++11+ support).

[YannickJadoul]

As I see our general example does not show how to use config variables.

There's a whole section "Options", right underneath the minimal example, so it should be reasonably clear if users read the docs?

adding a whole step that adds Python 2.7 but only works for C/C++<11

Is that still an issue on GitHub Actions (compared to Travis)? I thought everything was much more streamlined on GHA?
But yes, if that's the case, I can probably agree.

[YannickJadoul]

Is that still an issue on GitHub Actions (compared to Travis)?

Oh, I see, the installation step of the ancient Python 2.7 compiler is still there.

[Czaki]

There's a whole section "Options", right underneath the minimal example, so it should be reasonably clear if users read the docs?

There is rather a problem that you need to found how to set an environment variable in yaml file.
I think that it may be unclear that cibuildwheel build wheel on all python version if the environment variable is not set. I see examples with hole os times python version matrix.

[henryiii]

As I see it, this is just a demo of "simple" usage and the examples still exist for more realistic use cases. I think having a Python 3+ example on the main page, with a mention of how to find Python 2.7+ examples, would be fine. If you have a Python 3+ package, then this example is pretty close to complete. If you have a 2.7+ package, then the other example is wrong 50% of the time, since there are two choices for setting up the compiler on Windows. Plus it gives a real usage of the env variable setting, which 95% of all projects will likely need.

A full example would probably also show an upload job - this just makes the wheels available for download via the GitHub GUI (or for a later publish job). But it should be done as a separate job; that's easy to show in an example, but too verbose for a README.

Happy to go with whatever @joerick wants, though - just need confirmation of what to change.

[joerick]

I see there's a lot of discussion here over something quite small, which smells a little bikesheddy so I apologise for not jumping in sooner. I've thought about it, and I agree with @henryiii that building for Python 2.7 shouldn't be the default any longer:

• Python 2 has been deprecated for nearly a year
• supporting Python 2 makes the sample config longer and slower, because of the need to choco install the compiler.

So let's leave it out of this config, here on the README. It can remain in the minimal examples in the docs for now, but I'm also considering if it should go from there as well, since I'd bet that most people setting up cibuildwheel these days don't want to build for 2.7 either. If we remove it from the minimal configs, we could have a page in the docs "Building Python 2 wheels" that shows the choco install command

I've made a couple tweaks to the PR, hope that's okay @henryiii - just things that help make this more readable.