Deal properly with readme examples...

[altendky]

The examples in the readme can't be copied and pasted and run. They do not include imports, helpers, launchers... I think this may be ok, but it should be flagrantly obvious how to get an actually _runnable_ version. They are already included in the docs under examples but we need links at least. At the moment I tend to think that including the full file content in the readme is excessive? But I do also like complete examples so maybe someone can talk me into it.

So, how do we get there... it seems trivial but... let's take a little related detour and come back.

The readme examples are a little smelly right now in that they are just manually copied from the example .py files. The other entries in the docs use the reStructuredText include directive so they don't get out of date. GitHub declines to support this though in GitHub .rst rendering so the readme there can't use the include directive. I don't know how it works but there's similar consideration for the PyPI page. There's no indication the GitHub issue will be resolved... it's from 2012 and rejected.

So the basic difficulty is in how to get functional links in each of GitHub, PyPI and Read the Docs. A few months back there was an exploration of having the readme be generated from documentation using Sphinx with .rst output but we ran into various issues with the associated plugins, or something... #221

tl;dr doing this right should be simple, but isn't given the requirements.

[altendky]

github/markup#1104