<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>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.<br>
</p>
<p>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].</p>
<p>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.<br>
</p>
<p>[6]
<a class="moz-txt-link-freetext" href="https://devguide.python.org/documenting/#showing-code-examples">https://devguide.python.org/documenting/#showing-code-examples</a><br>
[7]
<a class="moz-txt-link-freetext" href="https://docs.readthedocs.io/en/latest/faq.html#i-want-to-use-the-blue-default-sphinx-theme">https://docs.readthedocs.io/en/latest/faq.html#i-want-to-use-the-blue-default-sphinx-theme</a><br>
[8] <a class="moz-txt-link-freetext" href="https://github.com/python/devguide">https://github.com/python/devguide</a><br>
</p>
<pre class="moz-signature" cols="72">Jeff Allen
</pre>
<div class="moz-cite-prefix">On 03/12/2017 04:49, Wes Turner wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CACfEFw_oCmsi9p-V=w8LGH_XcbTsSWsgNvi_6P+4O34HYYVOvA@mail.gmail.com">
<div>Add pygments for ``.. code::`` directive PEP syntax
highlighting #1206</div>
<div><a href="https://github.com/python/pythondotorg/issues/1206"
moz-do-not-send="true">https://github.com/python/pythondotorg/issues/1206</a></div>
<div><br>
</div>
<div>Syntax highlighting is an advantage for writers, editors, and
readers.</div>
<div><br>
</div>
<div>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``.</div>
<div><br>
</div>
<div>- GitHub shows Pygments syntax highlighting</div>
<div>for ``.. code::`` directives for .rst and .restructuredtext
documents</div>
<div>- PEPs may eventually be hosted on ReadTheDocs with Sphinx
(which installs docutils and pygments as install_requires in
setup.py).</div>
<div> <a href="https://github.com/python/peps/issues/2"
moz-do-not-send="true">https://github.com/python/peps/issues/2</a></div>
<div> <a href="https://github.com/python/core-workflow/issues/5"
moz-do-not-send="true">https://github.com/python/core-workflow/issues/5</a></div>
<div><br>
</div>
<div>In order to use pygments with pythondotorg-hosted PEPs, a few
things need to happen:</div>
<div><br>
</div>
<div>- [ ] Include ``pygments`` in ``base-requirements.txt``</div>
<div>- [ ] Pick a pygments theme</div>
<div> - Should we use the sphinx_rtd_theme default for
consistency with the eventual RTD-hosted PEPs?</div>
<div>- [ ] Include the necessary pygments CSS in the PEPs django
template</div>
<div>- [ ] rebuild the PEPs</div>
<div>- Start using code directives in new PEPs</div>
<div>- Manually review existing PEPs after adding code directives</div>
<div><br>
</div>
<div>PEPs may use ``.. code::`` blocks instead of ``::`` so that
code is syntax highlighted.</div>
<br>
On Saturday, December 2, 2017, Nick Coghlan <<a
href="mailto:ncoghlan@gmail.com" moz-do-not-send="true">ncoghlan@gmail.com</a>>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">On 3 December
2017 at 12:32, Wes Turner <<a href="javascript:;"
onclick="_e(event, 'cvml', 'wes.turner@gmail.com')"
moz-do-not-send="true">wes.turner@gmail.com</a>> wrote:<br>
> Pending a transition of PEPs to ReadTheDocs (with HTTPS on
a custom domain?<br>
> and redirects?) (is there a gh issue for this task?),<br>
<br>
See <a href="https://github.com/python/peps/projects/1"
target="_blank" moz-do-not-send="true">https://github.com/python/<wbr>peps/projects/1</a>
and<br>
<a href="https://github.com/python/core-workflow/issues/5"
target="_blank" moz-do-not-send="true">https://github.com/python/<wbr>core-workflow/issues/5</a><br>
<br>
Cheers,<br>
Nick.<br>
<br>
--<br>
Nick Coghlan | <a href="javascript:;" onclick="_e(event,
'cvml', 'ncoghlan@gmail.com')" moz-do-not-send="true">ncoghlan@gmail.com</a>
| Brisbane, Australia<br>
</blockquote>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Python-Dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Python-Dev@python.org">Python-Dev@python.org</a>
<a class="moz-txt-link-freetext" href="https://mail.python.org/mailman/listinfo/python-dev">https://mail.python.org/mailman/listinfo/python-dev</a>
Unsubscribe: <a class="moz-txt-link-freetext" href="https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk">https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk</a>
</pre>
</blockquote>
<br>
</body>
</html>