Reorganize documentation

[dean0x7d]

As discussed in #442, this PR reorganizes the documentation with the main focus on the Advanced topics. The .rst diffs are pretty much useless to look at. Instead, see the html preview build over here: http://pybind11-preview.readthedocs.io/en/latest/ (available for the lifetime of this PR).

So... I had a plan going into this, but that kind of fell out the window pretty soon after actually getting into the reorganization. But I think this should work. "Advanced topic" has turned into a top level separator with a few main topics. Most of the sections are nested with 2 levels, but there are also some 3 level ones (for casters and Python types). Each topic has a moderate number of sections which should make navigation a lot easier.

Thoughts? There are probably still some rough edges, but I figure it's better to show this earlier and get feedback rather than go down the wrong path.

Some "glue" text was added here and there (like at the beginning of "Functions" and "Classes") to smooth out the transitions. There were also a couple of changes outside Advanced:

• "Exporting constants and mutable objects" was moved from "Advanced" to "First steps" and modified somewhat. This is simple enough, so it felt right.
• The big table from "Supported data types" was moved from "First steps" to "Casting data types".

[jagerman]

Looks great, this is a major improvement IMO!

[wjakob]

This looks great. I wonder if it would make sense to rename two of the sections to emphasize the similarity between them:

Casting data types -> Type conversions
Python C++ interface -> Type wrappers

(or something of that sort)

For various types (e.g. STL data types, NumPy matrices), it's feasible to go with two fundamentally different solutions: converting between native C++/Python types, or working with a Python type wrapper on the C++ side. My impression is that this is highly confusing to new users.

[dean0x7d]

It may be good to have a quick section at the beginning of "Type conversions" which would specifically address that issue, i.e. the difference of converting to/from C++ types and the Python type wrappers. Maybe a quick example of how a list can be converted to either std::vector or py::list and the pros/cons of the two approaches. I don't think there should be any confusion if it's explained early on.

The "Type conversions" rename seems fine, but I'm not so sure about "Type wrappers" since that section is about more than types. It's not all documented yet, but there are lots of functions as well (len, eval, print, hasattr, getattr, etc.). Together with the types they're essential the start of a very nice Python C++ API which is more convenient to use than the official C API. In that sense, this section is pretty different compared to the type converters.

[wjakob]

It may be good to have a quick section at the beginning of "Type conversions" which would specifically address that issue, i.e. the difference of converting to/from C++ types and the Python type wrappers. Maybe a quick example of how a list can be converted to either std::vector or py::list and the pros/cons of the two approaches. I don't think there should be any confusion if it's explained early on.

.. and in that case there is also the possibility of pushing py::vector onto the Python side using stl_bind.h.

(Good point about the naming.)

[wjakob]

Let me know how you'd like to proceed. Shall I leave this open for longer or merge it now?

[dean0x7d]

I was thinking to do the "Type conversions" rename and write the conversion differences section, although I probably won't have time for it until Wednesday. But if you have something else in mind or you'd like to merge this now, that's fine as well.

[wjakob]

That is fine, I'll wait until Wednesday then. Thank you for your help with this!

[dean0x7d]

Updated PR and preview on RTD.

Type conversions: I think it's good to have the overview of the 3 different approaches. Although, I'm not sure how clear the text itself is.

Minor update for "Default arguments revisited": arg_t to arg_v since the former is deprecated.

[wjakob]

Looks great -- I think this is very clear. I'll merge this now.

One quick question: what do you think about merging all the casting chapters into the same page?
If you click on, say, http://pybind11-preview.readthedocs.io/en/latest/advanced/functions.html, there is a lot of material that is referenced in subsections in the TOC on the left and visible on the right.

When clicking http://pybind11-preview.readthedocs.io/en/latest/advanced/cast/index.html and just reading top to bottom, one might miss the fact that there is actually a lot more content that can be reached by clicking the right links.

What dou you think?

[dean0x7d]

Yeah, I was on the fence about that one. My main reasons for going with this arrangement were the subsubsections which felt like too much nesting (and length) for a single page. But I can also see it looking a little strange, especially since the index page isn't just a table of contents like "Python C++ interface" -- for that one I'm definitely in favor of keeping the multi-page layout, especially since it's under-documented at the moment and should receive a few expansions. But for "Type conversions" I don't have strong feelings either way, both layouts should work reasonably well.