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

[Jeff Allen]

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 [1] vs [2] and [3] in 
Wes' original post, but in addition there's a little section in the 
devguide [6].

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 [7]). There are other limitations. Browsing the devguide source 
[8] there gives a good idea what the GitHub can and cannot represent in 
this view.

[6] https://devguide.python.org/documenting/#showing-code-examples
[7] 
https://docs.readthedocs.io/en/latest/faq.html#i-want-to-use-the-blue-default-sphinx-theme
[8] https://github.com/python/devguide

Jeff Allen

On 03/12/2017 04:49, Wes Turner wrote:
> 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 
> <mailto: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
>     <https://github.com/python/peps/projects/1> and
>     https://github.com/python/core-workflow/issues/5
>     <https://github.com/python/core-workflow/issues/5>
>
>     Cheers,
>     Nick.
>
>     --
>     Nick Coghlan   | ncoghlan at gmail.com <javascript:;>  |   Brisbane,
>     Australia
>
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20171205/c10ff2f7/attachment.html>