README.rst: Add teaser (with `doctest` lexer)

[msabramo]

Because a teaser on the PyPI page is nice and changing the lexer from doctest to pycon will allow it to render in nice color on PyPI (and in the future on GitHub, when https://github.com/github/linguist/issues/1939 gets deployed).

[marca@marca-mac2 characteristic]$ pygmentize -L | egrep 'doctest|pycon'
* pycon:

Preview at https://github.com/msabramo/characteristic/tree/README_teaser

Preview of how it will look on GitHub when they deploy https://github.com/github/linguist/issues/1939 to production: lightshow

[coveralls]

Coverage remained the same at 100.0% when pulling b1749f8f3f6033c707d53de773ee9455404f5b63 on msabramo:README_teaser into 9bb38e78959f784a9aea3f2a91e7c74e34627cf6 on hynek:master.

[coveralls]

Coverage remained the same when pulling 8b6c157dce1d82b7f22dde84ffb7c69000e0af61 on msabramo:README_teaser into 9bb38e78959f784a9aea3f2a91e7c74e34627cf6 on hynek:master.

[hynek]

Hm yeah the fact that GitHub doesn’t render pycon is the sole reason why my projects don’t have their teasers in the README – good to know it’s gonna change soon!

One thing though: the docs include the contents of the README (see https://raw.githubusercontent.com/hynek/characteristic/master/docs/index.rst ) so as of now the teaser would appear twice.

[msabramo]

Oh should I amend this to remove the teaser from index.rst?

[hynek]

yeah, just build the sphinx docs (make html) and see for yourself. :)

[msabramo]

OK, updated.

[coveralls]

Coverage remained the same when pulling 2969bf58db684cdd5c70f3d40acca306a6b39345 on msabramo:README_teaser into 9bb38e78959f784a9aea3f2a91e7c74e34627cf6 on hynek:master.

[hynek]

Ahhhhh now I remember the right reason…pycon works but doctest doesn’t!

Do you think there’s a chance to convince GitHub to support doctest too? I really like to verify my examples. :)

Thanks for helping!

[msabramo]

Testing...

pycon

>>> a = {'animal': 'dog'}
>>> a
{'animal': 'dog'}
>>> print('yay')
yay

doctest

>>> a = {'animal': 'dog'}
>>> a
{'animal': 'dog'}
>>> print('yay')
yay

[msabramo]

@hynek:

Do you think there’s a chance to convince GitHub to support doctest too?

Well, we'll see what happens -- https://github.com/atom/language-python/pull/49 :smile:

[msabramo]

https://github.com/atom/language-python/pull/49 merged. So doctest should work in a few weeks. :smile:

[hynek]

w00t! Could you switch it back to doctest then?

[msabramo]

Done.

[msabramo]

Hmmmm, Pygments doesn't support a doctest lexer; only pycon. What to do?

[msabramo]

Just updated this so that README.rst includes the example as pycon and I moved .. begin after the teaser so the teaser doesn't appear twice in sphinx docs.

Preview README.rst at https://github.com/msabramo/characteristic/blob/README_teaser/README.rst

How does that look?

[coveralls]

Coverage remained the same when pulling e30ad2ac5c10365826b0ced9df60f047673f23c4 on msabramo:README_teaser into 8cd0d14385b00a28df0c1d9c2ce987bdcc126f17 on hynek:master.

[hynek]

I will play with this before I release 15.0. Maybe it’s possible to extract two parts. ponder