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

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.

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 !

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

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

Hi,

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

Bests

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

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.

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>

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

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

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

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

Here a new patch after reviewing comments on rietveld.

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

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.

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!

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.

Hi,

Indentation in whatsnew/3.2 fixed.

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

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?

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.

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.

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

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.

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

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.

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

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

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.

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

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