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

2017年12月04日 22:47:36 -0800

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 <[email protected] <mailto:[email protected]>> wrote: 
 On 3 December 2017 at 12:32, Wes Turner <[email protected]
 <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  | [email protected] <javascript:;> |  Brisbane,
 Australia
_______________________________________________
Python-Dev mailing list
[email protected]
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk

_______________________________________________
Python-Dev mailing list
[email protected]
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Reply via email to