Fixes #667

The sphinx version is pinned by readthedocs, but sphinx 1.3.5 is not
available with conda python 3.6. The workaround is to pin the python
version to 3.5 (it doesn't really matter for the docs build).

This reverts commit bee8827a.

* Propagate unicode conversion failure

If returning a std::string with invalid utf-8 data, we currently fail
with an uninformative TypeError instead of propagating the
UnicodeDecodeError that Python sets on failure.

* Add support for u16/u32strings and literals

This adds support for wchar{16,32}_t character literals and the
associated std::u{16,32}string types.  It also folds the
character/string conversion into a single type_caster template, since
the type casters for string and wstring were mostly the same anyway.

* Added too-long and too-big character conversion errors

With this commit, when casting to a single character, as opposed to a
C-style string, we make sure the input wasn't a multi-character string
or a single character with codepoint too large for the character type.

This also changes the character cast op to CharT instead of CharT& (we
need to be able to return a temporary decoded char value, but also
because there's little gained by bothering with an lvalue return here).

Finally it changes the char caster to 'has-a-string-caster' instead of
'is-a-string-caster' because, with the cast_op change above, there's
nothing at all gained from inheritance.  This also lets us remove the
`success` from the string caster (which was only there for the char
caster) into the char caster itself.  (I also renamed it to 'none' and
inverted its value to better reflect its purpose).  The None -> nullptr
loading also now takes place only under a `convert = true` load pass.
Although it's unlikely that a function taking a char also has overloads
that can take a None, it seems marginally more correct to treat it as a
conversion.

This commit simplifies the size assumptions about character sizes with
static_asserts to back them up.

Recent gcc snapshots (both gcc 7 snapshots and recent gcc 6 stable
branch snapshots) are triggering an upstream gcc bug when -flto is
enabled (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=79296).  This has
been hitting the gcc-7 builds for a while now, but is going to start
hitting the debian testing builds in a few days as well.

The issue is triggered by using -flto in combination with structs or
classes declared in a function, as done in test_alias_initialization,
test_isses, test_methods_and_attributes (and possibly more).

I'm subscribed to the upstream bug, and will submit another PR to
reenable LTO once a fixed gcc is available.

The gcc-7 build also generates some warnings; just ignore them for now
(by turning off -Werror).

This both lets us not bother rechecking LTO flags when cmake reinvokes
itself, and also lets the cmake invoker override to specify custom or
no LTO flags by setting the cache variable with
-DPYBIND11_LTO_CXX_FLAGS= when invoking cmake.

Clang on linux currently fails to run cmake:

    $ CC=clang CXX=clang++ cmake ..
    ...
    -- Configuring done
    CMake Error at tools/pybind11Tools.cmake:135 (target_compile_options):
      Error evaluating generator expression:

        $<:-flto>

      Expression did not evaluate to a known generator expression
    Call Stack (most recent call first):
      tests/CMakeLists.txt:68 (pybind11_add_module)

But investigating this led to various other -flto detection problems;
this commit thus overhauls LTO flag detection:

- -flto needs to be passed to the linker as well
- Also compile with -fno-fat-lto-objects under GCC
- Pass the equivalent flags to MSVC
- Enable LTO flags for via generator expressions (for non-debug builds
  only), so that multi-config builds (like on Windows) still work
  properly.  This seems reasonable, however, even on single-config
  builds (and simplifies the cmake code a bit).
- clang's lto linker plugins don't accept '-Os', so replace it with
  '-O3' when doing a MINSIZEREL build
- Enable trying ThinLTO by default for test suite (only affects clang)
- Match Clang$ rather than ^Clang$ because, for cmake with 3.0+
  policies in effect, the compiler ID will be AppleClang on macOS.

Use PROJECT_SOURCE_DIR instead of CMAKE_SOURCE_DIR as the base of the
path to libsize.py. This fixes an error if pybind11 is being built
directly within another project.

* Avoid C-style const casts

Replace C-style casts that discard `const` with `const_cast` (and, where
necessary, `reinterpret_cast` as well).

* Warn about C-style const-discarding casts

Change pybind11_enable_warnings to also enable `-Wcast-qual` (warn if a
C-style cast discards `const`) by default. The previous commit should
have gotten rid of all of these (at least, all the ones that tripped in
my build, which included the tests), and this should discourage more
from newly appearing.

Fixes #656.

Before this commit, the problematic sequence was:

1. `catch (const std::exception &e)` gets a Python exception,
   i.e. `error_already_set`.
2. `PyErr_SetString(PyExc_ImportError, e.what())` sets an `ImportError`.
3. `~error_already_set()` now runs, but `gil_scoped_acquire` fails due
   to an unhandled `ImportError` (which was just set in step 2).

This commit adds a separate catch block for Python exceptions which just
clears the Python error state a little earlier and replaces it with an
`ImportError`, thus making sure that there is only a single Python
exception in flight at a time. (After step 2 in the sequence above,
there were effectively two Python expections set.)

* Fix debugging output for nameless py::arg annotations

This fixes a couple bugs with nameless py::arg() (introduced in #634)
annotations:

- the argument name was being used in debug mode without checking that
  it exists (which would result in the std::string construction throwing
  an exception for being invoked with a nullptr)
- the error output says "keyword arguments", but py::arg_v() can now
  also be used for positional argument defaults.
- the debugging output "in function named 'blah'" was overly verbose:
  changed it to just "in function 'blah'".

* Fix missing space in debug test string

* Moved tests from issues to methods_and_attributes

Add a GitHub issue template

[skip ci]

(Identifiers starting with underscores are reserved by the standard)
Also fixed a typo in a comment.

Prefer non-converting argument overloads

Add support for non-converting arguments

This changes the function dispatching code for overloaded functions into
a two-pass procedure where we first try all overloads with
`convert=false` for all arguments.  If no function calls succeeds in the
first pass, we then try a second pass where we allow arguments to have
`convert=true` (unless, of course, the argument was explicitly specified
with `py::arg().noconvert()`).

For non-overloaded methods, the two-pass procedure is skipped (we just
make the overload-allowed call).  The second pass is also skipped if it
would result in the same thing (i.e. where all arguments are
`.noconvert()` arguments).

This adds support for controlling the `convert` flag of arguments
through the py::arg annotation.  This then allows arguments to be
flagged as non-converting, which the type_caster is able to use to
request different behaviour.

Currently, AFAICS `convert` is only used for type converters of regular
pybind11-registered types; all of the other core type_casters ignore it.
We can, however, repurpose it to control internal conversion of
converters like Eigen and `array`: most usefully to give callers a way
to disable the conversion that would otherwise occur when a
`Eigen::Ref<const Eigen::Matrix>` argument is passed a numpy array that
requires conversion (either because it has an incompatible stride or the
wrong dtype).

Specifying a noconvert looks like one of these:

    m.def("f1", &f, "a"_a.noconvert() = "default"); // Named, default, noconvert
    m.def("f2", &f, "a"_a.noconvert()); // Named, no default, no converting
    m.def("f3", &f, py::arg().noconvert()); // Unnamed, no default, no converting

(The last part--being able to declare a py::arg without a name--is new:
previous py::arg() only accepted named keyword arguments).

Such an non-convert argument is then passed `convert = false` by the
type caster when loading the argument.  Whether this has an effect is up
to the type caster itself, but as mentioned above, this would be
extremely helpful for the Eigen support to give a nicer way to specify
a "no-copy" mode than the custom wrapper in the current PR, and
moreover isn't an Eigen-specific hack.

Arithmetic and complex casters now only do a converting cast when
`convert=true`; previously they would convert always (e.g. when passing
an int to a float-accepting function, or a float to complex-accepting
function).

* Add documentation for strings and Unicode issues

* More Unicode documentation on character literals and wide characters

Issue #633 suggests people might be tempted to copy the test scripts
self-binding code, but that's a bad idea for pretty much anything other
than a test suite with self-contained test code.

This commit adds a comment as such with a reference to the
documentation that tells people how to do it instead.

* Minor doc syntax fix

The numpy documentation had a bad :file: reference (was using double
backticks instead of single backticks).

* Changed long-outdated "example" -> "tests" wording

The ConstructorStats internal docs still had "from example import", and
the main testing cpp file still used "example" in the module
description.

This cleans up the previous commit slightly by further reducing the
function call arguments to a single struct (containing the
function_record, arguments vector, and parent).

Although this doesn't currently change anything, it does allow for
future functionality to have a place for precalls to store temporary
objects that need to be destroyed after a function call (whether or not
the call succeeds).

As a concrete example, with this change #625 could be easily implemented
(I think) by adding a std::unique_ptr<gil_scoped_release> member to the
`function_call` struct with a precall that actually constructs it.
Without this, the precall can't do that: the postcall won't be invoked
if the call throws an exception.

This doesn't seems to affect the .so size noticeably (either way).

This keeps it with constexpr_sum and the other metafunctions.

Passing a negative value wasn't valid anyway, and moreover this avoids a
little bit of extra code to avoid signed/unsigned argument warnings.

This commit rewrites the function dispatcher code to support mixing
regular arguments with py::args/py::kwargs arguments.  It also
simplifies the argument loader noticeably as it no longer has to worry
about args/kwargs: all of that is now sorted out in the dispatcher,
which now simply appends a tuple/dict if the function takes
py::args/py::kwargs, then passes all the arguments in a vector.

When the argument loader hit a py::args or py::kwargs, it doesn't do
anything special: it just calls the appropriate type_caster just like it
does for any other argument (thus removing the previous special cases
for args/kwargs).

Switching to passing arguments in a single std::vector instead of a pair
of tuples also makes things simpler, both in the dispatch and the
argument_loader: since this argument list is strictly pybind-internal
(i.e. it never goes to Python) we have no particular reason to use a
Python tuple here.

Some (intentional) restrictions:
- you may not bind a function that has args/kwargs somewhere other than
  the end (this somewhat matches Python, and keeps the dispatch code a
  little cleaner by being able to not worry about where to inject the
  args/kwargs in the argument list).
- If you specify an argument both positionally and via a keyword
  argument, you get a TypeError alerting you to this (as you do in
  Python).

Adds a 32-bit (debian) build to travis-ci.

* Abstract away some holder functionality (resolve #585)

Custom holder types which don't have `.get()` can select the correct
function to call by specializing `holder_traits`.

* Add support for move-only holders (fix #605)

* Clarify PYBIND11_NUMPY_DTYPE documentation

The current documentation and example reads as though
PYBIND11_NUMPY_DTYPE is a declarative macro along the same lines as
PYBIND11_DECLARE_HOLDER_TYPE, but it isn't.  The changes the
documentation and docs example to make it clear that you need to "call"
the macro.

* Add satisfies_{all,any,none}_of<T, Preds>

`satisfies_all_of<T, Pred1, Pred2, Pred3>` is a nice legibility-enhanced
shortcut for `is_all<Pred1<T>, Pred2<T>, Pred3<T>>`.

* Give better error message for non-POD dtype attempts

If you try to use a non-POD data type, you get difficult-to-interpret
compilation errors (about ::name() not being a member of an internal
pybind11 struct, among others), for which isn't at all obvious what the
problem is.

This adds a static_assert for such cases.

It also changes the base case from an empty struct to the is_pod_struct
case by no longer using `enable_if<is_pod_struct>` but instead using a
static_assert: thus specializations avoid the base class, POD types
work, and non-POD types (and unimplemented POD types like std::array)
get a more informative static_assert failure.

* Prefix macros with PYBIND11_

numpy.h uses unprefixed macros, which seems undesirable.  This prefixes
them with PYBIND11_ to match all the other macros in numpy.h (and
elsewhere).

* Add long double support

This adds long double and std::complex<long double> support for numpy
arrays.

This allows some simplification of the code used to generate format
descriptors; the new code uses fewer macros, instead putting the code as
different templated options; the template conditions end up simpler with
this because we are now supporting all basic C++ arithmetic types (and
so can use is_arithmetic instead of is_integral + multiple
different specializations).

In addition to testing that it is indeed working in the test script, it
also adds various offset and size calculations there, which
fixes the test failures under x86 compilations.

fixed VS build, when _DEBUG is just defined without any value assigned (e.g. VS15)

* Make 'any' the default markup role for Sphinx docs

* Automate generation of reference docs with doxygen and breathe

* Improve reference docs coverage

* Some clarifications to section on virtual fns

Primarily, I made it clear that PYBIND11_OVERLOAD_PURE_NAME is not "useful" but required in renaming situations. Also clarified that one should not bind to the trampoline helper class which I found tempting since it seems more explicit.

* Remove :emphasize-lines: from cpp block, seems to suppress formatting

* docs: emphasize default policy, clarify keep_alive

Emphasize the default return value policy since this statement is hidden in a wall of text. 

Add a hint that call policies are probably required for container objects.

* [Doc] Fix several errors of examples from the doc

* Add missing operator def.

* Added missing `()`

* Add missing `namespace`.

Correct function signature of module init function generated PYBIND11_PLUGIN_IMPL macro for Python 2.x (#602)