[docs] Patch to enhance literal block language declaration (issue 26462)

python at mandark.fr python at mandark.fr
Tue Jul 26 05:21:30 EDT 2016

Thanks for all that feedback I should clearly have reviewed my patch
deeper, not prod of me... I'm submitting "issue26462.v5.diff", I'm
trying to generate a diff format that rietveld will understand but I'm
not sure to one-shot it, I'm using:

    git diff --staged | sed 's/^\(@@ .* @@\).*$/\1/g' | grep -v '^index'
> issue26462.v5.diff

(I may also learn to use mercurial, but as it look you're migrating to
git, I'm not sure it's worth the effort. But if it's the only way to
generate rietveld-compatible patches and it saves you time (by not
having to regenerate each of my patches), tell me and I'll do. If my sed
is enough, cool).

File Doc/extending/newtypes.rst (right):

Doc/extending/newtypes.rst:212: in a file called :file:`setup.py`; then
On 2016/07/26 08:32:56, vadmium wrote:
> Not a big deal, but I don’t think this colon is needed


File Doc/library/2to3.rst (right):

Doc/library/2to3.rst:63: can be given with :option:`-f`.  Likewise the
:option:`-x` explicitly disables a
On 2016/07/26 08:32:56, vadmium wrote:
> I presume this line was changed accidentally. The :option:`-x` link is
> see <https://bugs.python.org/issue26638> where I made this change.


File Doc/library/decimal.rst (right):

Doc/library/decimal.rst:168: .. doctest::
On 2016/07/26 08:32:56, vadmium wrote:
> $ make -C Doc/ doctest
> . . .
> WARNING: no code/output in doctest block at
> /media/disk/home/proj/python/cpython/Doc/library/decimal.rst:168
> Also, with or without this change, I get no highlighting. Perhaps
there should
> be a blank line inbetween?

Done, it was the wrong Traceback indentation.

Doc/library/decimal.rst:173: File "<stdin>", line 1, in <module>
On 2016/07/26 08:32:56, vadmium wrote:
> Or perhaps because of missing indentation here?

Done, it was exactly this.

Doc/library/decimal.rst:247: .. doctest::
On 2016/07/26 08:32:56, vadmium wrote:
> WARNING: no code/output in doctest block at
> /media/disk/home/proj/python/cpython/Doc/library/decimal.rst:247

Done. Missing newline after `.. doctest::`

File Doc/library/logging.config.rst (right):

Doc/library/logging.config.rst:635: Examples of these sections in the
file are given below. :
On 2016/07/26 08:32:56, vadmium wrote:
> This produces a floating colon (:) at the end of the line. Perhaps
remove it
> completely? (same problem below)


File Doc/library/pyexpat.rst (right):

Doc/library/pyexpat.rst:874: not. See
On 2016/07/26 08:32:56, vadmium wrote:
> This is reverting an unrelated change (Issue 26736). I suggest not to
mess with
> newlines in files you edit without a good reason.

Done, as my patch was a few month old it not merged properly, I should
have reviewed it myself in depth... sry for that.

File Doc/library/subprocess.rst (left):

Doc/library/subprocess.rst:960: # becomes
On 2016/07/26 08:32:56, vadmium wrote:
> These are all hybrid python3 and Unix shell code. I guess “python”
means Python
> 2, where `...` means repr(...).
> I guess we could split here into two blocks (Unix shell and python3)

Done (splitted).

File Doc/whatsnew/3.3.rst (left):

Doc/whatsnew/3.3.rst:1002: $ ./python -q
On 2016/07/26 08:32:56, vadmium wrote:
> I think you can just drop the python -q line instead

Done (removed the line).

File Doc/whatsnew/3.5.rst (right):

Doc/whatsnew/3.5.rst:294: .. code-block:: pycon
On 2016/07/26 08:32:56, vadmium wrote:
> $ make -C Doc/ suspicious PYTHON=python3
> . . .
> WARNING: [whatsnew/3.5:294] "::" found in ".. code-block:: pycon"
> Maybe the double colon (::) needs adjusting?
> In fact, why is this change needed at all? Maybe it is just that my
Sphinx or
> whatever needs updating to understand the new operator.

Without my buggy `::` I'm getting "Could not parse literal_block as
"pycon"", clearly our parsers are not up-to-date and should be fixed.
I'll see what I can do about it, but it's another unrelated patch so I
just drop this `.. code-block:: pycon` and keep the warning to
explicitly tell there's a problem here.


More information about the docs mailing list