classification
Title: Double parens in functions references
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, chris.jerdonek, docs@python, georg.brandl, python-dev, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2012-08-01 15:05 by serhiy.storchaka, last changed 2017-01-14 10:17 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
doc_dbl_parens.patch serhiy.storchaka, 2012-08-10 21:07 review
doc_dbl_parens_drop_markup.patch serhiy.storchaka, 2012-08-11 07:54 review
Messages (19)
msg167137 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-01 15:05
:c:func:`PyMem_Malloc(n)` on Doc/c-api/memory.rst:109 rendered in HTML as <tt class="xref c c-func docutils literal"><span class="pre">PyMem_Malloc(1)()</span></tt> (note double parents). There are many other examples on this and other pages. The issue is actual for all modern versions of Python.
msg167808 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-09 18:35
Fixed. 
Sorry, I forgot to mention issue number in commit messages.
So it's 9c99f31a9c2a 96cc3ab243e5 and 1e8f6d8e5c0e commits.
Thanks for report.
msg167810 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-08-09 18:51
These commit hashes don't seem to match this issue.
msg167815 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-09 18:56
Sorry, Georg. A'm apologizing.
Actual commit numbers are: 6dab233a115e a979b005a814 4787b9b2f860
msg167817 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-08-09 19:02
Thanks!
msg167818 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-09 19:05
Thank you for reviewing every minor update.
It's a big deal and heavy work!
msg167822 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-09 19:34
Hmm, I'm hoping that will be fixed by fixing of some markup words (:c:func:, :func:, :meth:, etc) processing, and not that they will simply be removed. :c:func: works only for function name without parameters or for function name with empty list of parameters inside the parentheses (:c:func:`PyMem_Malloc`, :c:func:`PyMem_Malloc()`, but not :c:func:`PyMem_Malloc(1)`). :c:macro: works also for non-empty list (:c:macro:`Py_CLEAR(obj)` for example).

And Doc/c-api/memory.rst is not only one issue file. The list of suspicious places you can get by the followed command:

    find Doc/ -type f -name '*.rst' -exec egrep -n --color ':`\w+[(][^)]' '{}' +
msg167824 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-08-09 19:42
The markup you mentioned will not be changed: these are two different usecases. Either you link to the function itself (:func:`blah`), or you show a piece of code (``blah(n)``).
msg167826 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-09 19:52
From my perspective sphinx doesn't allow notations like :c:func:`PyMem_Malloc(1)`
Do you want to publish bugfix for sphinx? Sounds like good idea, but that fix is out my current competence.
I just fixed weird stuff which you pointed out.
If you want to do more — you are welcome. Please push a patch.
msg167903 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-10 18:18
Sorry, I don't know anything about the Sphinx, therefore, I do not know what is the problem and what the solution should be.

1) If this is the improper use of markup (the arguments are not supported and must not), we need to remove markup from other doc files (Doc/library/os.rst, Doc/library/platform.rst, Doc/library/unittest.rst, Doc/whatsnew/2.0.rst, Doc/whatsnew/2.1.rst, Doc/whatsnew/2.2.rst, Doc/whatsnew/2.3.rst, Doc/whatsnew/2.4.rst, Doc/whatsnew/2.5.rst, Doc/whatsnew/3.0.rst).

2) If the behaviour of the markup is controlled by configuration files, which are under the management of the CPython team, then these configuration files should be fixed.

3) If the behaviour of the markup is hardcoded inside the Sphinx, then it is the Sphinx bug and it should be reported to Sphinx team. I don't know what CPython team can/should do with it.

Which of these variants is actual?

Note, :c:macro: works for names with arguments, and :c:func:, :func:, :meth: did not.
msg167904 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-08-10 18:22
1) is correct.

(And cmacro works because it's only for non-function macros anyway.)
msg167910 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-10 19:40
-   a distinct non-*NULL* pointer if possible, as if :c:func:`PyMem_Malloc(1)` had
+   a distinct non-*NULL* pointer if possible, as if ``PyMem_Malloc(1)`` had

> From my perspective sphinx doesn't allow notations like :c:func:`PyMem_Malloc(1)`

I believe that it does.  Sphinx allows you to specify link text distinct from the target for various roles:

http://docs.python.org/devguide/documenting.html#id3

So for the above, it would be--

:c:func:`PyMem_Malloc(1) <PyMem_Malloc>`

I confirmed that this works.  I think this is preferable to displaying the preferred text without any hyperlink.
msg167915 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-10 21:05
Thanks Chris. Here's the patch.
msg167935 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-08-11 06:32
Is anyone even reading my messages...?
msg167939 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-11 07:54
Georg, I see that :meth: with arguments works in the form :meth:`name(args) <module.class.name>`. I believe that the hyperlinks are helpful and it was designed that way.

Replacing :meth:/:func:/:c:func: for names with arguments on double backquotes can be done almost automatically. Here's another patch (I like it less).
msg167985 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-11 18:15
New changeset 5e025dc7d728 by Andrew Svetlov in branch 'default':
Issue #15527: fix docs, remove double parens by changing markup.
http://hg.python.org/cpython/rev/5e025dc7d728
msg167986 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-11 18:18
Applied patch uses ``expr(n)`` as Georg prefer.

Serhiy, please close the issue if you have not any upcoming patches.
Thanks.
msg167988 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-08-11 18:28
Thank you Andrew.
msg285471 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-01-14 10:17
New changeset be4da80b493e by Martin Panter in branch '2.7':
Issue #15527: remove double parens by changing markup.
https://hg.python.org/cpython/rev/be4da80b493e
History
Date User Action Args
2017-01-14 10:17:21python-devsetmessages: + msg285471
2012-08-11 18:28:29serhiy.storchakasetstatus: open -> closed
resolution: fixed
messages: + msg167988

stage: patch review -> resolved
2012-08-11 18:18:26asvetlovsetmessages: + msg167986
2012-08-11 18:15:13python-devsetnosy: + python-dev
messages: + msg167985
2012-08-11 07:54:36serhiy.storchakasetfiles: + doc_dbl_parens_drop_markup.patch

messages: + msg167939
2012-08-11 06:32:19georg.brandlsetmessages: + msg167935
2012-08-10 21:07:44serhiy.storchakasetfiles: + doc_dbl_parens.patch
2012-08-10 21:06:40serhiy.storchakasetkeywords: + patch
2012-08-10 21:05:59serhiy.storchakasetmessages: + msg167915
stage: needs patch -> patch review
2012-08-10 19:40:01chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg167910
2012-08-10 18:22:34georg.brandlsetmessages: + msg167904
2012-08-10 18:18:23serhiy.storchakasetmessages: + msg167903
2012-08-09 19:52:36asvetlovsetmessages: + msg167826
2012-08-09 19:42:40georg.brandlsetmessages: + msg167824
2012-08-09 19:34:18serhiy.storchakasetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg167822

stage: resolved -> needs patch
2012-08-09 19:05:39asvetlovsetmessages: + msg167818
2012-08-09 19:02:41georg.brandlsetmessages: + msg167817
2012-08-09 18:56:15asvetlovsetmessages: + msg167815
2012-08-09 18:51:01georg.brandlsetnosy: + georg.brandl
messages: + msg167810
2012-08-09 18:35:42asvetlovsetstatus: open -> closed
resolution: fixed
messages: + msg167808

stage: resolved
2012-08-09 13:14:48asvetlovsetnosy: + asvetlov
2012-08-01 15:41:15pitrousettitle: Double parents in functions references -> Double parens in functions references
2012-08-01 15:05:57serhiy.storchakacreate