classification
Title: Index "code object" and link to code object definition
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, martin.panter, python-dev, r.david.murray, rhettinger, tbeadle, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2012-07-28 07:11 by chris.jerdonek, last changed 2016-06-10 00:45 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch tbeadle, 2016-06-02 23:37 patch review
0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch tbeadle, 2016-06-03 02:48 Updated patch review
0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch tbeadle, 2016-06-03 17:27 Update based on Martin's comments review
0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch tbeadle, 2016-06-08 03:51 Updated patch review
Messages (18)
msg166633 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-28 07:11
This issue is to add "code object" to the documentation glossary, as discussed in issue 15457 regarding the documentation around generators.

This can be a minimal entry that links to the details here, for example--

http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy
specifically: http://docs.python.org/dev/reference/datamodel.html#index-52
msg169858 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-05 05:12
I am starting work on this in the next couple days.
msg169859 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-09-05 05:35
I disagree that this should be added.  The glossary is not intended to be a dictionary of every possible concept.  Ideally, it should remain short enough so that it can be read in a single sitting.   Making the docs fatter doesn't make them better.
msg169861 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-05 06:01
That's fine by me.  I guess what's more important to me is that "code object" have a central, linkable definition *somewhere* (and not necessarily that this somewhere be a glossary entry).  That way references to code object in the docs can link to a definition in the same way that we link to definitions of other words, functions, etc.

I was also planning on indexing the word more properly.
msg220644 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-15 14:54
Can this be closed given msg169859 and msg169861?
msg220660 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-06-15 18:20
There is no entry for 'code object' (unlike, for instance 'class object'). There is an entry for 'code' and a subentry for 'object' with four links.

The fourth link is to the short definition in the library manual:
https://docs.python.org/3/library/stdtypes.html#index-46
https://docs.python.org/3/library/stdtypes.html#code-objects
is better as it includes the header line. This is the one that should be used elsewhere.

The entry says "See The standard type hierarchy for more information."

The third link is to the long definition in the datamodel section.
https://docs.python.org/3/reference/datamodel.html#index-53
Again, the header line is cut off. I presume this is because the index directive is after rather than before the header line. I think the short definition should point directly here.

The second link is to code objects in the C-API
https://docs.python.org/3/c-api/code.html#index-0

The first link is to marshal, because marshal marshals code objects. 

In other words, the unlabeled links are in the reverse order of what one would want. More helpful would be something like

code object
  C-API
  definition
  marshal
msg266989 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-02 23:37
The attached patch makes it so that 'code object' is its own 'top-level' entry in the index instead of being 'code' with an 'object' sub-item.  It also makes the links from the index go to the location in the documents just before the header instead of having the header be off-screen when the user navigates to it.

One thing about the ordering of the generated links, though, is that sphinx appears to generate them based on the alphabetical ordering of the path to the files that they're in:

c-api/code.rst
library/marshal.rst
library/stdtypes.rst
reference/datamodel.rst

If the order is that important, I believe it would require us to create sub-items that could look like this:

code object
    C API
    built-in type
    type reference
    marshaling

It didn't seem like other indexed entries follow this breakout pattern, but if that's what's desired for this case, just let me know and I'll submit a different patch.
msg267011 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-03 00:43
Since the main object of the issue is to have a canonical reference to use for linking 'code object' from elsewhere in the text, I think that can be satisfied by existing _bltin-code-objects 'ref' link as Terry suggests, even though it is a bit awkward to use.  The changes to the index position are good, I think, as is having a direct index entry for 'code object'.  However, following the model laid down by 'class object', the existing index entries under object should not be lost, but instead the new 'code object' index links should be added.
msg267028 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-03 02:48
This restores the original code -> object items.
msg267068 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-03 07:14
I left some minor review suggestions. But a more serious problem is that the change to Doc/reference/datamodel.rst breaks the formatting for me. Instead of a HTML <dl>, I get a <p> followed by a <blockquote>. Unfortunately I don’t know of a way to get index entries to point to the definition list heading without breaking up a definition list like this.

IMO having entries under both “code object” and “code” is redundant, but I see that is debatable. :) If I was looking this up, I would probably look at “code” first. If it wasn’t there, I might even miss a separate “code object” entry, considering there is also a second “code (. . .)” entry as well.
msg267118 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-03 17:46
There are entries for code with object as a subentry?  That's not what I was talking about, I was talking about preserving the sub entries for 'code' under the 'object' main entry.
msg267142 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-03 19:15
Using

.. index::
   object: code

puts a 'code' entry under 'object' as well as 'object' under 'code'.  That's the way it is for every other item that uses "object: XXX".  So if you want a new 'code object' top-level item and keep 'object -> code', you're going to get 'code -> object' as well.  It would seem to me that the 'code object' top-level item is redundant.
msg267182 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-03 22:49
I haven’t tested, but maybe this will do what you want:

.. index:: object; code, code object

or

.. index::
   single: object; code
   single: code object
msg267189 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-03 23:35
Not sure why it doesn’t come up in the code review, but in

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index c0b4930..f34ba9f 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -847,8 +847,10 @@ Internal types

    Code objects
+
       .. index::
          single: bytecode
+         single: code object
          object: code
 
       Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.

that added blank line seems to also cause the same definition list problem as before :(
msg267773 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-08 03:51
Martin, thanks for the suggestion that worked.  I believe this patch should have all of the issues addressed.
msg267788 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-08 05:30
Yes it seems you even fixed the problem with the definition list, which I thought was not fixable :)
msg268068 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-09 23:53
New changeset 2e9aace7e10a by Tommy Beadle in branch '3.5':
[Issue 15476] Make "code object" its own entry in the index
https://hg.python.org/cpython/rev/2e9aace7e10a

New changeset 8455bbc6b4f2 by Martin Panter in branch 'default':
Issue #15476: Merge index entries from 3.5
https://hg.python.org/cpython/rev/8455bbc6b4f2

New changeset f89e96235a42 by Tommy Beadle in branch '2.7':
[Issue 15476] Make "code object" its own entry in the index
https://hg.python.org/cpython/rev/f89e96235a42
msg268071 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-10 00:45
Thanks for the patch Tommy. I think we can close this now.
History
Date User Action Args
2016-06-10 00:45:07martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg268071

stage: commit review -> resolved
2016-06-09 23:53:52python-devsetnosy: + python-dev
messages: + msg268068
2016-06-08 05:30:13martin.pantersetmessages: + msg267788
stage: needs patch -> commit review
2016-06-08 03:51:34tbeadlesetfiles: + 0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch

messages: + msg267773
2016-06-03 23:35:07martin.pantersetmessages: + msg267189
2016-06-03 22:49:33martin.pantersetmessages: + msg267182
2016-06-03 19:15:33tbeadlesetmessages: + msg267142
2016-06-03 17:46:10r.david.murraysetmessages: + msg267118
2016-06-03 17:27:53tbeadlesetfiles: + 0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch
2016-06-03 07:14:31martin.pantersetnosy: + martin.panter

messages: + msg267068
versions: + Python 2.7, Python 3.5, Python 3.6, - Python 3.3
2016-06-03 02:48:24tbeadlesetfiles: + 0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch

messages: + msg267028
2016-06-03 01:04:19BreamoreBoysetnosy: - BreamoreBoy
2016-06-03 00:43:16r.david.murraysetnosy: + r.david.murray
messages: + msg267011
2016-06-02 23:37:01tbeadlesetfiles: + 0001-Issue-15476-Make-code-object-its-own-entry-in-the-do.patch

nosy: + tbeadle
messages: + msg266989

keywords: + patch
2014-06-15 18:20:29terry.reedysetmessages: + msg220660
title: Add "code object" to glossary -> Index "code object" and link to code object definition
2014-06-15 14:54:13BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220644
2012-09-05 06:01:42chris.jerdoneksetmessages: + msg169861
2012-09-05 05:35:00rhettingersetnosy: + rhettinger
messages: + msg169859
2012-09-05 05:12:56chris.jerdoneksetmessages: + msg169858
2012-09-05 05:10:55chris.jerdoneklinkissue15457 dependencies
2012-07-28 07:11:11chris.jerdonekcreate