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

I am starting work on this in the next couple days.

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.

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.

Can this be closed given msg169859 and msg169861?

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

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.

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.

This restores the original code -> object items.

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.

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.

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.

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

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 :(

Martin, thanks for the suggestion that worked.  I believe this patch should have all of the issues addressed.

Yes it seems you even fixed the problem with the definition list, which I thought was not fixable :)

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

Thanks for the patch Tommy. I think we can close this now.