[STACK] Refactor certain doctests towards either reStructuredText documentation or Python tests

[amotl]

About

This is a stab at #448, to improve the shape of doctests vs. rendered documentation. It moves some doctest files around into the documentation directory, and dissolves others into pure-Python tests.

New documentation section

The doctest files referenced below are now becoming first citizens of the public documentation, within a dedicated "by example" section. To make sure they are always valid, they are still evaluated as doctests. Many thanks to the authors who originally conceived them.

After adding some introductory paragraphs to the individual files, I think the new content is sweet already, and will be even better after another iteration of more content-related edits and refactorings by a subsequent patch.

Here, it is rendered as a preview on RTD, see CrateDB Python client by example.

Details

• doctests/{client,http,blob}.txt and doctests/{connection,cursor,https}.txt have been moved to the documentation, to be rendered as reStructuredText (10da69c5f8, 1731cc558).
• All SQLAlchemy-related doctests are now also part of the documentation, that is doctests/sqlalchemy.rst and sqlalchemy/doctests/{dialect,itests,reflection}.txt (13ed96f2).
• On the other hand, doctests/layer.txt and doctests/mocking.txt are now implemented as regular Python tests.

Backlog

Within subsequent patches, those topics could be addressed.

• [ ] Improve the overall flow of the documenation.
• [x] Remove any kinds of symbol aliases from the doctest launcher established per test.globs, in order not to obfuscate them away from the users reading the examples, and likely aiming to just copy/paste the presented code snippets.
• [ ] Rework the documentation about blobs. Currently, it is scattered between docs/blobs.rst, docs/by-example/http.rst, and docs/by-example/blob.rst, and apparently outlines different access variants or stages. Let's sort this out.
• [ ] Add docs/*.rst to the test suite as well. Currently, they are not.