Add a public `stbt.draw_text` api

Based on the previously internal Display.draw_text, but now made
publicly available.
The draw_text method is now imported for use with stbt-run.
A unit test has also been added to confirm that the text is drawn
correctly.
test_draw_text: Disable on Mac OS X

Because the GStreamer elements vp8enc and webmmux don't work on OS X
so this test would always fail.
test_draw_text: Cleanup: Wrap long lines

And reorder arguments for consistency with the other tests.
test_draw_text: Cleanup: Use `--save-video` instead of explicit sink pipeline

The effect is the same; this is just simpler.
test_draw_text: Don't continue with test if early steps fail

If the first `stbt-run` fails, the second `stbt-run` is bound to fail
too, so the test would correctly report a failure both with and without
this commit. However the log output from the second `stbt-run` would be
confusing; this way you only see the relevant error from the first
`stbt-run`.
test_draw_text: Use "live" videotestsrc

videotestsrc generates frames as fast as it can, which on a typical
system is much faster than 24 frames per second. The `duration_secs`
parameter of `stbt.draw_frames` acts on the timestamps from the video
stream, not the wall-clock time, so using `duration_secs=3` resulted
in the text being displayed only for a very brief period of time (too
fast to even see it).

Though the previous implementation did work, it might give the
impression that `duration_secs` takes a number in milliseconds.

There are two ways to slow down the videotestsrc to real time: Set the
sink to `sync=true` (we use `sync=false`; see `sink_pipeline` in
tests/stbt.conf), or set videotestsrc's `is-live` property. `sync=true`
causes other problems (due to the delays and jitter introduced by the
image processing) so we use `videotestsrc is-live=true`.
stbt-run: Don't bring `draw_text` into script's namespace

We want to encourage users to explicitly `import stbt` in their scripts,
because it's more pythonic and less "magical", and it allows running
pylint over the scripts. Other recent new functions like `frames` and
`get_config` weren't added to this list for the same reason.

This was added in b6a6c015, but was never part of a tagged release so we
can still remove it from the public API. We'll eventually deprecate
these, and later remove this code altogether, but for now it remains for
compatibility with existing user scripts.
Document `stbt.draw_text` in the official API doc

Note that the change to README.rst is the result of running `make doc`
after the change to api-doc.sh.

I edited the docstring so that it displayed nicely in the generated
manpage (the docstrings and README are in reStructuredText format, so
you need a double linebreak in the source to get a new paragraph in the
output).
Merge branch 'draw_text'

* draw_text:
  Document `stbt.draw_text` in the official API doc
  stbt-run: Don't bring `draw_text` into script's namespace
  test_draw_text: Use "live" videotestsrc
  test_draw_text: Don't continue with test if early steps fail
  test_draw_text: Cleanup: Use `--save-video` instead of explicit sink pipeline
  test_draw_text: Cleanup: Wrap long lines
  test_draw_text: Disable on Mac OS X
  Add a public `stbt.draw_text` api