This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Use :role:`sys.thing` instead of ``sys.thing`` throughout
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: eric.araujo, ezio.melotti, georg.brandl, louiscipher, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2011-06-09 16:22 by eric.araujo, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue12301.test_patch louiscipher, 2011-08-06 18:16 review
issue-12031.patch louiscipher, 2011-09-10 16:43
Messages (20)
msg138004 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-09 16:22
In a great number of files, the ``code`` markup is used instead of the :data: role, which would create a link to the appropriate definition.

Unless someone objects, I would like to change all of them.
msg138150 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-06-11 02:44
Links are good ;-).
msg140782 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-07-21 05:10
+1
msg141721 - (view) Author: Bryce Verdier (louiscipher) Date: 2011-08-06 16:47
I would like to help out with this, as there seems to be a lot of work that needs to be done.

I guess I'm a little unsure about what you mean by ``code`` instead of :data:. Is ``code`` generic? Like in Doc/tutorials/classes.rst I see a lot of things similar to ``eval()``. Are you saying that dhould be changed to :data:eval()?
msg141722 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-06 17:00
Nope, ``...`` can be used for generic pieces of code, whereas e.g. :data:`sys.stdout` indicates that stdout is a "data" attribute of the sys module.
If you use :data:`...` and rebuild the doc (cd Doc/; make html), you will see that e.g. sys.stdout will be then a link to the sys.html page.
msg141725 - (view) Author: Bryce Verdier (louiscipher) Date: 2011-08-06 18:16
Is this more what was in mind for the bug?
msg141728 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-08-06 21:00
I presume so. I believe ``x`` is meant for general code like ``for thing in group: print(thing)``. While Éric specifically mentioned the :data: role, I presume the same idea applies to :func: and possibly other link-generating roles.

Is there a statement role, so that "effect of the ``global`` statement, " could be changed to link to the global statement doc?

This seems like a great project for a beginning developer to contribute patches.

Georg, do you have any reason to not have markup become more specific?
msg141730 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-06 22:32
For global there's :keyword:.  Also note that :data: should be used for module-level variables (or constant) not for attributes of e.g. classes and instances.

If there are other ``...`` that can be fixed (even using something else like e.g. :func: or :meth:), they should be fixed as well, but apparently ``...`` was often misused instead of :data: (maybe :data: was a recent addition).
msg141779 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-08 14:31
> I would like to help out with this, as there seems to be a lot of
> work that needs to be done.

Thanks!  In my initial report, I was talking only about module-level names that are documented as code (``sys.path``) instead of module-level data (:data:`sys.path`); the point is that the latter form creates a link to the doc of the module-level name.

I wasn’t aware that some functions and keywords used code markup instead or link-creating markup, like you found out for eval and getattr.  These should be fixed too.

Terry: You’re right, ``x`` is the most generic markup for inline code in reST.  It is used for command lines, program options that are not Python’s options (see #9312), bits of Python code, etc.

Now, about the amount of work needed: Don’t waste hours looking for all of these in the docs!  If you know basic shell commands, it’s easy to have *all* instances of ``sys.path`` changed to :data:`sys.path` in one go.  The thing requiring human attention is first listing all of the misuses of ````, second reviewing the changes.
msg141780 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-08 14:35
instead of*

An addition: in some cases, it may be on purpose that someone used ``somename`` instead of :func:`somename`, for example to avoid a ton of link in the doc of the somename function.  For the most part however, I believe it was just unawareness (or maybe unavailability) of the :data: construct that explains its absence.

One last precision: markup like ``getattr(spam, ham)`` should stay untouched: it is a code snippet, not just a reference to the function.
msg141783 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-08 14:42
``...`` should also be used for common names like True, False, None (no one needs links to their doc to see what they are), or, as Éric said, to avoid creating links for each occurrence of a name (one such example is the name of a module in the page that documents it).

I think that ``getattr(spam, ham)`` could be also written as :func:`getattr(spam, ham) <getattr>` in case you want to generate explicitly a link to getattr.  However in most of the cases this is not necessary.
msg141796 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-08-08 18:09
Changing ``x`` to :data:`x` adds 4 chars.
Changing ``x()`` to :func:`x` justs adds 2.
If I were to review, I would prefer that the additions not trigger cascading line rewraps.
msg143778 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-09 17:33
After thinking about this, I think it may be easier for everyone if I just did the change.  It’s just a list of boring grep-sed combos to run, and it’s easier if a core dev just does it instead of reviewing a long patch.  Sorry if you invested time, Bryce.
msg143843 - (view) Author: Bryce Verdier (louiscipher) Date: 2011-09-10 16:43
No worries, I totally understand. I was working on it a little bit at a time, as life would allow. And being probably more thorough than I needed to be. Here is the patch of everything that I've accomplished. Hope this helps.
msg143905 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-12 15:29
Thanks Bryce, I will start from your patch.  (BTW, you used func instead of data for sys.stdout.)
msg143923 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-09-12 17:25
It would be best to think about each of the new links individually rather than making blanket changes.   

The new links need to have relevance and add value to the topic; otherwise, they are just distractions from the more relevant links that had been placed there in a thoughtful manner.

For example, I don't think the docs are improved by turning every ``sys.stderr`` into a link.  How does that help users or does it just make the docs harder to read and obscure the move useful links.
msg143926 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-09-12 18:26
I agree.
msg143971 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-13 14:09
Alright, I’ll propose piecemeal patches.

Georg, two questions:
1) In the tutorial, should classes with no target use ``MyClass`` or :class:`!MyClass`?  

2) Should file extensions use ``.py`` or :file:`.py`?  We currently have both.
msg143976 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-09-13 15:26
Basically, :class:`!Foo` has no advantage over ``Foo``. The no-linking syntax is really only there for completeness, but I would prefer the plainer and easier to read (in source) ``Foo``.

For files, :file: really only has an advantage if you do something with the information that it's a file (which we don't, currently), or if you use the special feature that you can embed variable parts with {}.
msg302310 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-09-16 02:09
Inclined to reject this, given the general dislike of huge low-value patches.
History
Date User Action Args
2022-04-11 14:57:18adminsetgithub: 56510
2017-09-22 20:39:41eric.araujosetstatus: pending -> closed
resolution: rejected
stage: patch review -> resolved
2017-09-16 02:09:25eric.araujosetkeywords: - easy
status: open -> pending
messages: + msg302310

versions: - Python 2.7, Python 3.2, Python 3.3, Python 3.4
2013-03-02 13:05:33ezio.melottisettype: enhancement
versions: + Python 3.4
2011-09-13 15:26:59georg.brandlsetmessages: + msg143976
2011-09-13 14:09:22eric.araujosetmessages: + msg143971
2011-09-12 18:26:12georg.brandlsetmessages: + msg143926
2011-09-12 17:25:19rhettingersetnosy: + rhettinger
messages: + msg143923
2011-09-12 15:29:56eric.araujosettitle: Use :data:`sys.thing` instead of ``sys.thing`` throughout -> Use :role:`sys.thing` instead of ``sys.thing`` throughout
messages: + msg143905
stage: needs patch -> patch review
2011-09-10 16:43:28louisciphersetfiles: + issue-12031.patch
keywords: + patch
messages: + msg143843
2011-09-09 17:33:29eric.araujosetmessages: + msg143778
2011-08-08 18:09:45terry.reedysetmessages: + msg141796
2011-08-08 14:42:56ezio.melottisetmessages: + msg141783
2011-08-08 14:35:05eric.araujosetmessages: + msg141780
2011-08-08 14:31:20eric.araujosetmessages: + msg141779
2011-08-06 22:32:12ezio.melottisetmessages: + msg141730
2011-08-06 21:00:20terry.reedysetnosy: + georg.brandl
messages: + msg141728
2011-08-06 18:16:39louisciphersetfiles: + issue12301.test_patch

messages: + msg141725
2011-08-06 17:00:57ezio.melottisetmessages: + msg141722
2011-08-06 16:47:37louisciphersetnosy: + louiscipher
messages: + msg141721
2011-07-21 05:10:59ezio.melottisetkeywords: + easy

messages: + msg140782
2011-06-11 02:44:23terry.reedysetnosy: + terry.reedy

messages: + msg138150
stage: needs patch
2011-06-09 16:23:21ezio.melottisetnosy: + ezio.melotti
2011-06-09 16:22:29eric.araujocreate