* added overload for l-value ref-qualified methods

* Added test.
Before, the code would have failed to build.

* (docs) convert note to real note

* (docs) Add information about (deep)copy

For rationale, see #2241, eeb10448;
there is a second entry point function defined by the PYBIND11_MODULE
macro that also needs to be annotated as unused.

This change defines a new, portable macro PYBIND11_MAYBE_UNUSED to
mark declarations as unused, and annotates the PYBIND11_MODULE entry
point with this attribute.

The purpose of this annotation is to facilitate dead code detection,
which might otherwise consider the module entry point function dead,
since it isn't otherwise used. (It is only used via FFI.)

Add warnings about extending STL

Primarily for the ccmake curses GUI

* Test on Python 3.9 beta
* Pin Sphinx
* Newer version of PyPy

This reverts commit 9ed8b440.

* Add AutoWIG to list of binding generators

This adds support for a `py::args_kw_only()` annotation that can be
specified between `py::arg` annotations to indicate that any following
arguments are keyword-only.  This allows you to write:

    m.def("f", [](int a, int b) { /* ... */ },
          py::arg("a"), py::args_kw_only(), py::arg("b"));

and have it work like Python 3's:

    def f(a, *, b):
        # ...

with respect to how `a` and `b` arguments are accepted (that is, `a` can
be positional or by keyword; `b` can only be specified by keyword).

- Not currently supported on PyPy

__init__(self) cannot return values. According to https://stackoverflow.com/questions/2491819/how-to-return-a-value-from-init-in-python __new__(cls) should be used, which works.

This variable is a CMake community standard to set the C++
standard of a build. Document it in favor of the previous variable,
which stays as a legacy flag for existing projects.

https://cmake.org/cmake/help/v3.17/variable/CMAKE_CXX_STANDARD.html

With this change, and cast.h as-is in master, test_tagbased_polymorphic.cpp fails to compile with the error message below.
With the cast.h change in pull/2016, building and testing succeeds.

cd pybind11/build/tests && /usr/bin/c++  -DPYBIND11_TEST_BOOST -DPYBIND11_TEST_EIGEN -Dpybind11_tests_EXPORTS -Ipybind11/include -I/usr/include/python3.7m -isystem /usr/include/eigen3  -Os -DNDEBUG -fPIC -fvisibility=hidden   -std=c++2a -flto -fno-fat-lto-objects -Wall -Wextra -Wconversion -Wcast-qual -Wdeprecated -o CMakeFiles/pybind11_tests.dir/test_tagbased_polymorphic.cpp.o -c pybind11/tests/test_tagbased_polymorphic.cpp
In file included from pybind11/include/pybind11/attr.h:13,
                 from pybind11/include/pybind11/pybind11.h:44,
                 from pybind11/tests/pybind11_tests.h:2,
                 from pybind11/tests/test_tagbased_polymorphic.cpp:10:
pybind11/include/pybind11/cast.h: In instantiation of ‘static std::pair<const void*, const pybind11::detail::type_info*> pybind11::detail::type_caster_base<type>::src_and_type(const itype*) [with type = Animal; pybind11::detail::type_caster_base<type>::itype = Animal]’:
pybind11/include/pybind11/cast.h:906:31:   required from ‘static pybind11::handle pybind11::detail::type_caster_base<type>::cast_holder(const itype*, const void*) [with type = Animal; pybind11::detail::type_caster_base<type>::itype = Animal]’
pybind11/include/pybind11/cast.h:1566:51:   required from ‘static pybind11::handle pybind11::detail::move_only_holder_caster<type, holder_type>::cast(holder_type&&, pybind11::return_value_policy, pybind11::handle) [with type = Animal; holder_type = std::unique_ptr<Animal>]’
pybind11/include/pybind11/stl.h:175:69:   required from ‘static pybind11::handle pybind11::detail::list_caster<Type, Value>::cast(T&&, pybind11::return_value_policy, pybind11::handle) [with T = std::vector<std::unique_ptr<Animal> >; Type = std::vector<std::unique_ptr<Animal> >; Value = std::unique_ptr<Animal>]’
pybind11/include/pybind11/pybind11.h:159:43:   required from ‘void pybind11::cpp_function::initialize(Func&&, Return (*)(Args ...), const Extra& ...) [with Func = std::vector<std::unique_ptr<Animal> > (*&)(); Return = std::vector<std::unique_ptr<Animal> >; Args = {}; Extra = {pybind11::name, pybind11::scope, pybind11::sibling}]’
pybind11/include/pybind11/pybind11.h:64:9:   required from ‘pybind11::cpp_function::cpp_function(Return (*)(Args ...), const Extra& ...) [with Return = std::vector<std::unique_ptr<Animal> >; Args = {}; Extra = {pybind11::name, pybind11::scope, pybind11::sibling}]’
pybind11/include/pybind11/pybind11.h:819:22:   required from ‘pybind11::module& pybind11::module::def(const char*, Func&&, const Extra& ...) [with Func = std::vector<std::unique_ptr<Animal> > (*)(); Extra = {}]’
pybind11/tests/test_tagbased_polymorphic.cpp:141:36:   required from here
pybind11/include/pybind11/cast.h:880:61: error: ambiguous template instantiation for ‘struct pybind11::polymorphic_type_hook<Animal, void>’
         const void *vsrc = polymorphic_type_hook<itype>::get(src, instance_type);
                            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~
pybind11/include/pybind11/cast.h:844:8: note: candidates are: ‘template<class itype> struct pybind11::polymorphic_type_hook<itype, typename std::enable_if<std::is_polymorphic<_Tp>::value, void>::type> [with itype = Animal]’
 struct polymorphic_type_hook<itype, detail::enable_if_t<std::is_polymorphic<itype>::value>>
        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pybind11/tests/test_tagbased_polymorphic.cpp:115:12: note:                 ‘template<class itype> struct pybind11::polymorphic_type_hook<itype, typename std::enable_if<std::is_base_of<Animal, itype>::value, void>::type> [with itype = Animal]’
     struct polymorphic_type_hook<itype, detail::enable_if_t<std::is_base_of<Animal, itype>::value>>
            ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In file included from pybind11/include/pybind11/attr.h:13,
                 from pybind11/include/pybind11/pybind11.h:44,
                 from pybind11/tests/pybind11_tests.h:2,
                 from pybind11/tests/test_tagbased_polymorphic.cpp:10:
pybind11/include/pybind11/cast.h:880:61: error: incomplete type ‘pybind11::polymorphic_type_hook<Animal, void>’ used in nested name specifier
         const void *vsrc = polymorphic_type_hook<itype>::get(src, instance_type);
                            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~

Currently user specializations of the form

template <typename itype> struct polymorphic_type_hook<itype, std::enable_if_t<...>> { ... };

will fail if itype is also polymorphic, because the existing specialization will also
be enabled, which leads to 2 equally viable candidates. With this change, user provided
specializations have higher priority than the built in specialization for polymorphic types.

When binding code immediately throws an exception of type
py::error_already_set (e.g. via py::module::import that fails), the
catch block sets an import error as expected. Unfortunately, following
this, the deconstructor of py::error_already_set decides to call
py::detail::get_internals() and set up various internal data structures
of pybind11, which fails given that the error flag is active. The call
stack of this looks as follows:

Py_init_mymodule() -> __cxa_decrement_exception_refcount ->
error_already_set::~error_already_set() ->
gil_scoped_acquire::gil_scoped_acquire() -> detail::get_internals() ->
... -> pybind11::detail::simple_collector() -> uh oh..

The solution is simple: we call detail::get_internals() once before
running any binding code to make sure that the internal data structures
are ready.