[issue15476] Add "code object" to glossary
New submission from Chris Jerdonek <chris.jerdonek@gmail.com>: 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 ---------- assignee: docs@python components: Documentation keywords: easy messages: 166633 nosy: cjerdonek, docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Add "code object" to glossary type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Chris Jerdonek added the comment: I am starting work on this in the next couple days. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Raymond Hettinger added the comment: 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. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Chris Jerdonek added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Mark Lawrence added the comment: Can this be closed given msg169859 and msg169861? ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Terry J. Reedy added the comment: 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 ---------- title: Add "code object" to glossary -> Index "code object" and link to code object definition _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Tommy Beadle added the comment: 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. ---------- keywords: +patch nosy: +tbeadle Added file: http://bugs.python.org/file43126/0001-Issue-15476-Make-code-object-its-own-e... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
R. David Murray added the comment: 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. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Changes by Mark Lawrence <breamoreboy@yahoo.co.uk>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Tommy Beadle added the comment: This restores the original code -> object items. ---------- Added file: http://bugs.python.org/file43137/0001-Issue-15476-Make-code-object-its-own-e... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Martin Panter added the comment: 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. ---------- nosy: +martin.panter versions: +Python 2.7, Python 3.5, Python 3.6 -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Changes by Tommy Beadle <tbeadle@gmail.com>: Added file: http://bugs.python.org/file43152/0001-Issue-15476-Make-code-object-its-own-e... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
R. David Murray added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Tommy Beadle added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Martin Panter added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Martin Panter added the comment: 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 :( ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Tommy Beadle added the comment: Martin, thanks for the suggestion that worked. I believe this patch should have all of the issues addressed. ---------- Added file: http://bugs.python.org/file43298/0001-Issue-15476-Make-code-object-its-own-e... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Martin Panter added the comment: Yes it seems you even fixed the problem with the definition list, which I thought was not fixable :) ---------- stage: needs patch -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
Martin Panter added the comment: Thanks for the patch Tommy. I think we can close this now. ---------- resolution: -> fixed stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________
participants (8)
-
Chris Jerdonek -
Mark Lawrence
-
Martin Panter
-
R. David Murray
-
Raymond Hettinger
-
Roundup Robot
-
Terry J. Reedy
-
Tommy Beadle