Add pygments for .. code:: directive PEP syntax highlighting · Issue #1206 · python/pythondotorg (original) (raw)

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).
  Build PEPs using Sphinx peps#2
  Move the PEPs to Read the Docs core-workflow#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:: directives instead of :: so that code is syntax highlighted.