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

Jeff Allen 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:: ". The "::" shorthand works, meaning to take the language from the last ".. highlight:: " 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 installrequires 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 sphinxrtdtheme 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>

More information about the Python-Dev mailing list