Patch to enhance literal block language declaration

[JulienPalard]

BPO	26462
Nosy	@birkenfeld, @bitdancer, @vadmium, @zware, @serhiy-storchaka, @JulienPalard, @AraHaan
Files	literal_blocks_languages.patch: Patch to enhance literal blocks languages literal_blocks_languages.patch issue26462_regen.diff issue26462.diff issue26462.v3_regen.diff issue26462.diff issue26462.v4_regen.diff issue26462.v5.diff issue26462.v5_regen.diff issue26462.v6.diff issue26462.v7.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-08-05.08:47:32.263>
created_at = <Date 2016-02-29.23:58:50.667>
labels = ['type-feature', 'docs']
title = 'Patch to enhance literal block language declaration'
updated_at = <Date 2016-08-05.08:47:32.261>
user = 'https://github.com/JulienPalard'

bugs.python.org fields:

activity = <Date 2016-08-05.08:47:32.261>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-08-05.08:47:32.263>
closer = 'martin.panter'
components = ['Documentation']
creation = <Date 2016-02-29.23:58:50.667>
creator = 'mdk'
dependencies = []
files = ['42050', '42057', '42058', '43847', '43872', '43874', '43885', '43892', '43915', '43916', '43923']
hgrepos = []
issue_num = 26462
keywords = ['patch']
message_count = 30.0
messages = ['261035', '261039', '261076', '261079', '261097', '271080', '271105', '271117', '271232', '271241', '271242', '271263', '271332', '271350', '271351', '271509', '271511', '271521', '271548', '271549', '271550', '271551', '271553', '271554', '271560', '271566', '271596', '271597', '272004', '272019']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'r.david.murray', 'docs@python', 'python-dev', 'martin.panter', 'zach.ware', 'serhiy.storchaka', 'mdk', 'Decorater']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26462'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[JulienPalard]

Hi,

As I don't like warnings, and sphinx-doc was verbose about "Could not parse literal_block as "python3". highlighting skipped.", I fixed most of them.

Bonus: It's graphically better, as an example the XML block here: https://docs.python.org/3.5/library/pyexpat.html is now nicely colored: http://www.afpy.org/doc/python/3.5/library/pyexpat.html

[birkenfeld]

Thanks for the patch!

Most "bash" blocks should be "console" (since the prompt is shown). "pycon" should not be needed, since it is detected automatically.

[JulienPalard]

I revewed all my ".. code-block:: bash" and you're right (I was unaware of the existence of the "console" lexer). I changed them (reviewing them one by one) to ".. code-block:: shell-session", a synonym for ".. code-block:: console" (http://pygments.org/docs/lexers/?highlight=console#pygments.lexers.shell.BashSessionLexer) which I find, in a Python context, semantically more precise, and less ambigious, as one may read "console" as "the repl" (I assume most writers of the doc are aware of commonly used pygment lexers, it's still better for newcomers to be explicit and readable).

For your other point, about pycon being automatically detected, I tried removeing them and it works, I was sure I was adding them only where the python3 parser was reporting an error (was fixing errors one by one). I keeped the explicit pycon lexer in the "Doc/extending/extending.rst" file which have a ".. highlightlang:: c".

Here is the new patch, and thanks for this usefull review !

[zware]

Attaching regenerated patch to coax Rietveld into accepting it for easier review.

[birkenfeld]

Looks good now! I left a few comments on Rietveld.

[JulienPalard]

Hi,

Look like it has not been merged, is there something I can do to help with this?

Bests

[zware]

Hi Julien, there are still a few unanswered review comments. Check the 'review' link on 'issue26462_regen.diff' (which was your patch, I just recreated it in a format that our Rietveld review tool would accept).

[JulienPalard]

Hi,

I completly missed the "review" link, sry. I reviewed comments, and I'm trying to provide an up-to-date patch that you'll hopefully won't have to doctor to make Rietveld eat it.

[vadmium]

With Julien’s patch applied, these are the remaining warnings:

/media/disk/home/proj/python/cpython/Doc/library/configparser.rst:240: WARNING: Could not lex literal_block as "ini". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/library/configparser.rst:301: WARNING: Could not lex literal_block as "ini". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/library/configparser.rst:332: WARNING: Could not lex literal_block as "ini". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/library/configparser.rst:341: WARNING: Could not lex literal_block as "ini". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/reference/lexical_analysis.rst:799: WARNING: Could not lex literal_block as "python3". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/reference/lexical_analysis.rst:813: WARNING: Could not lex literal_block as "python3". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/whatsnew/2.4.rst:1430: WARNING: Could not lex literal_block as "python3". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/whatsnew/3.5.rst:285: WARNING: Could not lex literal_block as "python3". Highlighting skipped.
/media/disk/home/proj/python/cpython/Doc/whatsnew/3.5.rst:294: WARNING: Could not lex literal_block as "python3". Highlighting skipped.

Also, perhaps you didn’t see Georg’s comment in some unpatched code: <http://bugs.python.org/review/26462/diff/16666/Doc/library/logging.config.rst#newcode703\>

[JulienPalard]

Upladed a new patch, I was working on 3.5 branch so I did not get all errors.

I'm still having:

WARNING: Could not parse literal_block as "ini". highlighting skipped.

But it may be considered another bug: pygments ini parser can't parse ini syntax used in configparser doc (probably due to the columns usage instead of equals signs): I prefer having an "can't parse ini" on an ini paragraph than "can't parse python3".

[JulienPalard]

Oh and, is there a proper way for me to generate a diff that rietveld can eat without someone regeneratig it?

[vadmium]

I think generating it with Mercurial (and not using Mercurial’s Git patch format) is the best way. I just left some more notes at <https://bugs.python.org/issue13963#msg271260\>.