(original) (raw)

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  

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@gmail.com> wrote:

On 3 December 2017 at 12:32, Wes Turner <wes.turner@gmail.com> 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 and
https://github.com/python/core-workflow/issues/5

Cheers,
Nick.

\--
Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_  
Python-Dev mailing list  
Python-Dev@python.org  
https://mail.python.org/mailman/listinfo/python-dev  
Unsubscribe: https://mail.python.org/mailman/options/python-dev/ja.py%40farowl.co.uk