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)

This way a non-CACHE variable can also be used. For example:
```
set(PYBIND11_PYTHON_VERSION <value>)
add_subdirectory(...)
```

On a debian jessie machine, running 'python --version --noconftest' caused
pytest to try and run the test suite with the not-yet-compiled extension
module, thus failing the test. This commit chages the pytest detection
so that it only attempts to run an import statement.

Both are no longer needed: debian testing has Python 2.7.13 final now,
and wheels of numpy and scipy are available.

Fixes #567.

If pybind's CMakeLists gets loaded via an include_directory from another
CMakeLists with a higher minimum version (e.g. 3.0), the project()
command without a version produces a CMP0048 warning.

This commit explicitly requests the new behaviour if the policy exists,
as it won't cause problems (we set VERSION later).

* Fixed a regression that was introduced in the PyPy patch: use ht_qualname_meta instead of ht_qualname to fix PyHeapTypeObject->ht_qualname field.

* Added a qualname/repr test that works in both Python 3.3+ and previous versions

* Temporarily allows osx homebrew Python 3.6 to fail.

https://github.com/pybind/pybind11/pull/570#issuecomment-269120613

"Homebrew just got Python 3.6 (brew install python3), but numpy and scipy don't have binary wheels for 3.6 yet so it's trying to compile from source and failing."

Makes room for an eventual pybind11::embedded target.

See the documentation for a description of the options.

Add a BUILD_INTERFACE and a pybind11::pybind11 alias for the interface
library to match the installed target.

Add new cmake tests for add_subdirectory and consolidates the
.cpp and .py files needed for the cmake build tests:

Before:
tests
|-- test_installed_module
|   |-- CMakeLists.txt
|   |-- main.cpp
|   \-- test.py
\-- test_installed_target
    |-- CMakeLists.txt
    |-- main.cpp
    \-- test.py

After:
tests
\-- test_cmake_build
    |-- installed_module/CMakeLists.txt
    |-- installed_target/CMakeLists.txt
    |-- subdirectory_module/CMakeLists.txt
    |-- subdirectory_target/CMakeLists.txt
    |-- main.cpp
    \-- test.py

This commit includes modifications that are needed to get pybind11 to work with PyPy. The full test suite compiles and runs except for a last few functions that are commented out (due to problems in PyPy that were reported on the PyPy bugtracker).

Two somewhat intrusive changes were needed to make it possible: two new tags ``py::buffer_protocol()`` and ``py::metaclass()`` must now be specified to the ``class_`` constructor if the class uses the buffer protocol and/or requires a metaclass (e.g. for static properties).

Note that this is only for the PyPy version based on Python 2.7 for now. When the PyPy 3.x has caught up in terms of cpyext compliance, a PyPy 3.x patch will follow.

* always_construct_holder feature to support intrusively reference-counted types

* added testcase

Current debian testing has Python 2.7.13-RC1, which has a serious
regression (upstream https://bugs.python.org/issue5322) which should be
reverted for RC2 (or the final 2.7.13).  Ignore build failures for this
build test temporarily (with the intention of reverting this commit in a
couple of weeks once it stops failing, i.e. when debian testing picks up
an updated python 2.7 release).