classification
Title: availability directive breaks po files
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, georg.brandl, mdk, miss-islington, vstinner, xtreak
Priority: deferred blocker Keywords: patch

Created on 2018-10-18 08:50 by mdk, last changed 2018-11-07 21:48 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 10360 merged mdk, 2018-11-06 08:22
PR 10399 merged miss-islington, 2018-11-07 21:42
Messages (10)
msg327946 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-10-18 08:50
The new availability directive introduced in  2d6097d027e0dd3debbabc702aa9c98d94ba32a3 (https://bugs.python.org/issue11233) breaks po files (sphinx-build -b gettext):

Here's the diff I'm getting on os.po from os.rst:

 msgid ""
-"Availability: Unix, Windows.  :func:`spawnlp`, :func:`spawnlpe`, :func:"
-"`spawnvp` and :func:`spawnvpe` are not available on Windows.  :func:"
-"`spawnle` and :func:`spawnve` are not thread-safe on Windows; we advise you "
-"to use the :mod:`subprocess` module instead."
+"Availability: Unix, Windows.  spawnlp(), spawnlpe(), spawnvp() and "
+"spawnvpe() are not available on Windows.  spawnle() and spawnve() are not "
+"thread-safe on Windows; we advise you to use the subprocess module instead."

The roles has been removed in the po files (but not in the original rst files), so it looks like the availability directive caused the drop of roles, but I still don't understand why.
msg327971 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-18 12:19
Do you think it needs to be added to Doc\tools\templates?
msg327972 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-18 12:21
Sorry, I meant dummy.html in Docs\tools\templates.
msg327973 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-10-18 12:25
No, at first glance it looks like the implementation of the directive in pyspecific.py is "removing" the roles.

It's however not removing the roles while building the html, only removing it from po files, so there's a subtility I can't catch here (just spotted this, didn't have time to diagnose it in depth myself).
msg328001 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-18 19:43
I found this in the Sphinx doc.  This works on the English-language build OK, so I'm not sure if it's the cause of the issue.

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#gotchas

> No nested inline markup: Something like *see :func:`foo`* is not possible.
msg328005 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-18 21:14
Hum, the english HTML rendering looks good to me:
https://docs.python.org/dev/library/os.html#os.spawnvpe

So only the PO files are broken, right?
msg328015 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2018-10-19 01:29
@Cheryl I think it's about nested inline markup. The func is wrapped inside a * and the markup is normal is not nested here. I tried a sample directive as below :

..availability: :func:`len`

PO file

Availability: len()

Expected

Availability: :func:`len`

@Victor Yes, PO files are broken and markup is good. They have :func:`len` converted to len() like a method call in the output. Since markdown works fine I guess there is some configuration missing in the custom directive code to ensure translations work the same since there are directives like versionadded that have :func: that work fine in PO files. I tried debugging gettext.py in sphinx where catalog of messages are returned without markup as noted for Availablity directive and then written to the file. I don't know how to go little above the call stack to debug further since sphinx configuration looks very complicated.

Thanks

P.S. On mobile please ignore formatting errors if any
msg328042 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-10-19 13:07
Cross-posting here in case it's a sphinx issue: https://github.com/sphinx-doc/sphinx/issues/5554

Tried to debug it a bit at lunch time but the docutils API is still opaque to my eyes :(
msg329442 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-11-07 21:42
New changeset beed84ca5e0f2784d758478d4e7c81c9c1088c4e by Julien Palard in branch 'master':
bpo-35015: Doc: Fix internationalisation of the availability directive. (GH-10360)
https://github.com/python/cpython/commit/beed84ca5e0f2784d758478d4e7c81c9c1088c4e
msg329443 - (view) Author: miss-islington (miss-islington) Date: 2018-11-07 21:48
New changeset 363839caf9dac796783c74b682a70680a15fa8a7 by Miss Islington (bot) in branch '3.7':
bpo-35015: Doc: Fix internationalisation of the availability directive. (GH-10360)
https://github.com/python/cpython/commit/363839caf9dac796783c74b682a70680a15fa8a7
History
Date User Action Args
2018-11-07 21:48:50miss-islingtonsetnosy: + miss-islington
messages: + msg329443
2018-11-07 21:48:41mdksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-11-07 21:42:55miss-islingtonsetpull_requests: + pull_request9684
2018-11-07 21:42:46mdksetmessages: + msg329442
2018-11-06 08:22:24mdksetkeywords: + patch
stage: patch review
pull_requests: + pull_request9660
2018-10-19 13:07:50mdksetmessages: + msg328042
2018-10-19 01:29:58xtreaksetmessages: + msg328015
2018-10-18 21:14:09vstinnersetmessages: + msg328005
2018-10-18 19:43:42cheryl.sabellasetmessages: + msg328001
2018-10-18 17:07:51ned.deilysetpriority: normal -> deferred blocker
nosy: + vstinner

versions: + Python 3.7
2018-10-18 12:57:45xtreaksetnosy: + xtreak
2018-10-18 12:25:46mdksetmessages: + msg327973
2018-10-18 12:21:09cheryl.sabellasetmessages: + msg327972
2018-10-18 12:19:37cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg327971
2018-10-18 08:50:28mdkcreate