[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

I backported the patch to 2.7. Now I get no warnings about syntax highlighting 
from 2.7 (there were only a few reported before).

--
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Roundup Robot]

Roundup Robot added the comment:

New changeset 6e9a040a993f by Martin Panter in branch '2.7':
Issue #26462: Doc: avoid literal_block warnings, fix syntax highlighting.
https://hg.python.org/cpython/rev/6e9a040a993f

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

Okay, leaving this open for a 2.7 patch. BTW thanks for your work; I tried to 
tackle these warnings a while ago, but I didn’t know enough about 
Sphix/RST/etc. The 2.7 change should be fairly easy; I can give it a crack if 
you’re not that interested in 2.7.

--
stage: commit review -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Changes by Martin Panter :


--
versions: +Python 2.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Roundup Robot]

Roundup Robot added the comment:

New changeset 8bac90be by Martin Panter in branch '3.5':
Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
https://hg.python.org/cpython/rev/8bac90be

New changeset 6fbb7c9d77c6 by Martin Panter in branch 'default':
Issue #26462: Merge code block fixes from 3.5
https://hg.python.org/cpython/rev/6fbb7c9d77c6

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Decorater: Colors used by the documentation are defined here: 
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/pygments_styles.py#L22 
you can easily modify it and rebuild the doc ``(cd Doc; make html)``. Take a 
look at existing themes (https://help.farbox.com/pygments.html), sphinx uses a 
vaiarion of "friendly". But, in general, please open a new issue to speak on 
different subjects, typically about asyncio which is not related to this issue. 
Have a nice day.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Martin: OK, let's apply this to 3.6 / 3.5 with this one, and I'll provide 
independent patch for 2.7 if needed (long time without building 2.7 doc).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[R. David Murray]

R. David Murray added the comment:

Martin: your summary is correct.  A new feature should also have a What's New 
entry, of course; I think that's the only essential you left out.

Decorator: general comments (eg: color of docs, etc) aren't really useful 
comments on a specific bug report, and the asyncio comment is totally 
irrelevant.

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

Usually my technique is to apply the 3.6 patch to 3.5, fix up any conflicts, 
and leave the 3.6-only bits out (which get rejected by the patch process 
anyway). But dedicated patch(es) may be useful. Especially for 2.7, where there 
are probably independent changes to be made (e.g. modules that were removed in 
Python 3).

I think the policy on documentation in each branch should be in the devguide. 
My understanding: In general, bug fix branches (3.5, 2.7) have the 
documentation maintained, but generally not the older security-only branches.

My view is if a feature is added to (say) 3.6, then it gets a new-in-3.6 notice 
in the 3.6 documentation, but nothing gets added to 3.5. The Python 3 
documentation rarely mentions features of Python 2, so every feature is treated 
as being new in 3.0 by default. For Python 2, it won’t document new features of 
Python 3, but is updated with changes relevant to porting to 3. So in theory 
the latest Python 3.6+ documentation should also be usable with 3.5, but not 
with Python 2. That’s about all I know :)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Decorater]

Decorater added the comment:

Also I was thinking maybe I could figure out how to Add in asyncio to 2.7 
anyway (well latest one that is) because why not. With as many things using 
asyncio now days it would be cake for those python 2 users.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Decorater]

Decorater added the comment:

tbh it would be nice if the entire documentation was recolored to look more 
'interesting' to read. And to also have it in a way that people who lean 
visually can learn the info easier instead of them trying to read a giant wall 
of text that they may or may not understand. (got to hate reading giant walls) 
But yeah all versions on it should be good.

--
nosy: +Decorater

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Hi,

Would you like me to also provide patches for different versions?
I only provided patches for the default branch, but I'll gladly see this 
applied on other branches, as I often build them all.

Also is a documented policy about maintaining the documentation?
I have some questions like:

- Should we maintain bugfix/security/end-of-life branches?
- Are we even allowed to push a documentation change to them?
- I'm seeing that the 3.x documentation are converging by using the "New in 
version 3.xx." marks, but they still different, is this effort documented? 
- Is this a goal to merge them on the long term?
- Is there a team on this?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Hi,

Indentation in whatsnew/3.2 fixed.

Colors in this block are clearly not perfect, but I think that's another 
subject.

--
Added file: http://bugs.python.org/file43923/issue26462.v7.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

One last change I think needs making to the same demo, the “code-block” needs 
indenting under the bullet point:

* The interpreter can now be started with a quiet option, ``-q``, to prevent
  the copyright and version information from being displayed in the interactive
  mode.  The option can be introspected using the :attr:`sys.flags` attribute:
  
  .. code-block:: shell-session  <== Indented
 
$ python -q

Otherwise, it seems to include extra text in the code block.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Hi,

You're right, nice catch!

Removing `python -q` from the code block demonstrating it was a bad idea. I 
fixed it in the v6.

Thanks!

--
Added file: http://bugs.python.org/file43916/issue26462.v6.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

V5 looks pretty good to me. With your blessing of restoring the python -q 
example from v4 (see review), I think it is ready to commit.

--
stage: patch review -> commit review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Changes by Martin Panter :


Added file: http://bugs.python.org/file43915/issue26462.v5_regen.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

@martin I reviewed my changes on `decimal.rst` and I now just fixing the 
indentation problem, so I don't change anything unrealated to fixing warnings, 
and don't break doctests.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Here a new patch after reviewing comments on rietveld.

--
Added file: http://bugs.python.org/file43892/issue26462.v5.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

I’ve finished going over the latest patch. There are a couple of problems; see 
the review link.

Also, why did you add the changes in Doc/library/decimal.rst? In your second 
patch, you removed one of these changes, but now you have added more. They seem 
to reduce the number of doctests reported (make -C Doc/ doctest).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Changes by Martin Panter :


Added file: http://bugs.python.org/file43885/issue26462.v4_regen.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

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 
.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

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".

--
Added file: http://bugs.python.org/file43874/issue26462.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Martin Panter added the comment:

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: 


--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Martin Panter]

Changes by Martin Panter :


Added file: http://bugs.python.org/file43872/issue26462.v3_regen.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

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.

--
Added file: http://bugs.python.org/file43847/issue26462.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Zachary Ware]

Zachary Ware added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

Hi,

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

Bests

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Georg Brandl]

Georg Brandl added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Zachary Ware]

Zachary Ware added the comment:

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

--
nosy: +zach.ware
Added file: http://bugs.python.org/file42058/issue26462_regen.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

Julien added the comment:

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 !

--
Added file: http://bugs.python.org/file42057/literal_blocks_languages.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Georg Brandl]

Georg Brandl added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
nosy: +georg.brandl, serhiy.storchaka
stage:  -> patch review
versions: +Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26462] Patch to enhance literal block language declaration

[Julien]

New submission from Julien:

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

--
assignee: docs@python
components: Documentation
files: literal_blocks_languages.patch
keywords: patch
messages: 261035
nosy: docs@python, sizeof
priority: normal
severity: normal
status: open
title: Patch to enhance literal block language declaration
type: enhancement
versions: Python 3.5
Added file: http://bugs.python.org/file42050/literal_blocks_languages.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com