Add Pygments support

[nlhkabu]

It would be great if code rendered in long descriptions could be syntax highlighted with a library like pygments.

I can handle the actual selection and application of colors in the CSS, if someone else is happy to integrate the library that applies the classes. Related #800.

[dstufft]

Hmm, we should already be doing this too.

[dstufft]

Yes, if you take a look at https://warehouse-staging.python.org/project/dstufft.cryptography/ it already has the classes there. It just needs styled.

[nlhkabu]

OK. So then, any code that is coming through without Pygments support (e.g. https://warehouse-staging.python.org/project/python-ldap-test/) is because the source file doesn't support it?

Would it be worthwhile documenting how users should write their READMEs so that they get code highlighting on PyPI? ping @ddbeck

[dstufft]

Yea, they probably aren't instructing the rst renderer as to what language it is. Generally you want to do something like (taken from pyca/cryptography):

.. code-block:: pycon

    >>> from cryptography.fernet import Fernet
    >>> # Put this somewhere safe!
    >>> key = Fernet.generate_key()
    >>> f = Fernet(key)
    >>> token = f.encrypt(b"A really secret message. Not for prying eyes.")
    >>> token
    '...'
    >>> f.decrypt(token)
    'A really secret message. Not for prying eyes.'

The name (like pycon) can be anything that shows up as a shortname from http://pygments.org/docs/lexers/.

[ryanhiebert]

For my stuff on PyPI I've found that unrecognized languages also stop it from parsing. For example, with https://pypi.python.org/pypi/tox-travis, I have an example YAML file, and while GitHub recognized the rST, PyPI did not, and so assumed it was plain text. I had to remove the language specifier so PyPI would format it at all.

[ddbeck]

@nlhkabu Sorry not getting to this quicker! I already had it in mind to briefly encourage readmes in the new tutorial about making packages, so I suppose the next step would be to provide guidelines on including a PyPI-friendly readme as well. I've opened a new issue for the idea.

On another note, @ryanhiebert's report on unrecognized languages suggests that it would be nice if unrecognized lexers fell back to plain text rather than unformatted text. I'm not sure if that's something that would need to change in pygments or warehouse (or somewhere else) though.

[dstufft]

That'd be in https://github.com/pypa/readme probably.