[Python-Dev] PEPs: ``.. code:: python`` or ``::`` (syntax highlighting)
ja.py at farowl.co.uk
Tue Dec 5 01:11:32 EST 2017
The way this is expressed to docutils is slightly different from the way
it would be expressed to Sphinx. I expected someone would mention this
in relation to a possible move to RTD and Sphinx for PEPs and potential
to have to re-work the ReST. Sorry if this was obvious, and the re-work
simply too trivial to mention.
Both use pygments, but the directive to Sphinx is ".. code-block::
<language>". The "::" shorthand works, meaning to take the language from
the last ".. highlight:: <language>" directive, or conf.py (usually
"python"). This may be got from the references  vs  and  in
Wes' original post, but in addition there's a little section in the
In my experience, when browsing a .rst file, GitHub recognises my code
blocks (Sphinx "code-block::") and it colours Python (and Java) but not
Python console. It does not use the scheme chosen in conf.py (but nor
does RTD ). There are other limitations. Browsing the devguide source
 there gives a good idea what the GitHub can and cannot represent in
On 03/12/2017 04:49, Wes Turner wrote:
> 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).
> 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
> <mailto:ncoghlan at gmail.com>> wrote:
> On 3 December 2017 at 12:32, Wes Turner <wes.turner at gmail.com
> > 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
> <https://github.com/python/peps/projects/1> and
> Python-Dev mailing list
> Python-Dev at python.org
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-Dev