feat: setup.py redesign and helpers (#2433)

* feat: setup.py redesign and helpers

* refactor: simpler design with two outputs

* refactor: helper file update and Windows support

* fix: review points from @YannickJadoul

* refactor: fixes to naming and more docs

* feat: more customization points

* feat: add entry point pybind11-config

* refactor: Try Extension-focused method

* refactor: rename alt/inplace to global

* fix: allow usage with git modules, better docs

* feat: global as an extra (@YannickJadoul's suggestion)

* feat: single version location

* fix: remove the requirement that setuptools must be imported first

* fix: some review points from @wjacob

* fix: use .in, add procedure to docs

* refactor: avoid monkeypatch copy

* docs: minor typos corrected

* fix: minor points from @YannickJadoul

* fix: typo on Windows C++ mode

* fix: MSVC 15 update 3+ have c++14 flag

See <https://docs.microsoft.com/en-us/cpp/build/reference/std-specify-language-standard-version?view=vs-2019>

* docs: discuss making SDists by hand

* ci: use pep517.build instead of manual setup.py

* refactor: more comments from @YannickJadoul

* docs: updates from @ktbarrett

* fix: change to newly recommended tool instead of pep517.build

This was intended as a proof of concept; build seems to be the correct replacement.

See https://github.com/pypa/pep517/pull/83

* docs: updates from @wjakob

* refactor: dual version locations

* docs: typo spotted by @wjakob

tests/extra_setuptools/test_setuphelper.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+import os
+import sys
+import subprocess
+from textwrap import dedent
+
+import pytest
+
+DIR = os.path.abspath(os.path.dirname(__file__))
+MAIN_DIR = os.path.dirname(os.path.dirname(DIR))
+
+
+@pytest.mark.parametrize("std", [11, 0])
+def test_simple_setup_py(monkeypatch, tmpdir, std):
+    monkeypatch.chdir(tmpdir)
+    monkeypatch.syspath_prepend(MAIN_DIR)
+
+    (tmpdir / "setup.py").write_text(
+        dedent(
+            u"""\
+            import sys
+            sys.path.append({MAIN_DIR!r})
+
+            from setuptools import setup, Extension
+            from pybind11.setup_helpers import build_ext, Pybind11Extension
+
+            std = {std}
+
+            ext_modules = [
+                Pybind11Extension(
+                    "simple_setup",
+                    sorted(["main.cpp"]),
+                    cxx_std=std,
+                ),
+            ]
+
+            cmdclass = dict()
+            if std == 0:
+                cmdclass["build_ext"] = build_ext
+
+
+            setup(
+                name="simple_setup_package",
+                cmdclass=cmdclass,
+                ext_modules=ext_modules,
+            )
+            """
+        ).format(MAIN_DIR=MAIN_DIR, std=std),
+        encoding="ascii",
+    )
+
+    (tmpdir / "main.cpp").write_text(
+        dedent(
+            u"""\
+            #include <pybind11/pybind11.h>
+
+            int f(int x) {
+                return x * 3;
+            }
+            PYBIND11_MODULE(simple_setup, m) {
+                m.def("f", &f);
+            }
+            """
+        ),
+        encoding="ascii",
+    )
+
+    subprocess.check_call(
+        [sys.executable, "setup.py", "build_ext", "--inplace"],
+        stdout=sys.stdout,
+        stderr=sys.stderr,
+    )
+
+    # Debug helper printout, normally hidden
+    for item in tmpdir.listdir():
+        print(item.basename)
+
+    assert (
+        len([f for f in tmpdir.listdir() if f.basename.startswith("simple_setup")]) == 1
+    )
+    assert len(list(tmpdir.listdir())) == 4  # two files + output + build_dir
+
+    (tmpdir / "test.py").write_text(
+        dedent(
+            u"""\
+            import simple_setup
+            assert simple_setup.f(3) == 9
+            """
+        ),
+        encoding="ascii",
+    )
+
+    subprocess.check_call(
+        [sys.executable, "test.py"], stdout=sys.stdout, stderr=sys.stderr
+    )