[Python-Dev] PEPs: ``.. code:: python`` or ``::`` (syntax highlighting)

[Wes Turner]

Add pygments for ``.. code::`` directive PEP syntax highlighting #1206
https://github.com/python/pythondotorg/issues/1206

Syntax highlighting is an advantage for writers, editors, and readers.

reStructuredText PEPs are rendered into HTML with docutils. Syntax
highlighting in Docutils 0.9+ is powered by Pygments. If Pygments is not
installed, or there is a syntax error, syntax highlighting is absent.
Docutils renders ``.. code::`` blocks with Python syntax highlighting by
default. You can specify ``.. code:: python`` or ``.. code:: python3``.

- GitHub shows Pygments syntax highlighting
for ``.. code::`` directives for .rst and .restructuredtext documents
- PEPs may eventually be hosted on ReadTheDocs with Sphinx (which installs
docutils and pygments as install_requires in setup.py).
  https://github.com/python/peps/issues/2
  https://github.com/python/core-workflow/issues/5

In order to use pygments with pythondotorg-hosted PEPs, a few things need
to happen:

- [ ] Include ``pygments`` in ``base-requirements.txt``
- [ ] Pick a pygments theme
  - Should we use the sphinx_rtd_theme default for consistency with the
eventual RTD-hosted PEPs?
- [ ] Include the necessary pygments CSS in the PEPs django template
- [ ] rebuild the PEPs
- Start using code directives in new PEPs
- Manually review existing PEPs after adding code directives

PEPs may use ``.. code::`` blocks instead of ``::`` so that code is syntax
highlighted.

On Saturday, December 2, 2017, Nick Coghlan <ncoghlan at gmail.com> wrote:

> On 3 December 2017 at 12:32, Wes Turner <wes.turner at gmail.com
> <javascript:;>> wrote:
> > Pending a transition of PEPs to ReadTheDocs (with HTTPS on a custom
> domain?
> > and redirects?) (is there a gh issue for this task?),
>
> See https://github.com/python/peps/projects/1 and
> https://github.com/python/core-workflow/issues/5
>
> Cheers,
> Nick.
>
> --
> Nick Coghlan   |   ncoghlan at gmail.com <javascript:;>   |   Brisbane,
> Australia
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20171202/aff9389d/attachment.html>