(original) (raw)

Add pygments for \`\`.. code::\`\` directive PEP syntax highlighting #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.