Conversation
More clearly describe `shares_memory` as being not always *feasible* rather than *possible*
Also reworded `stride` entry for clarity, moved 'axis' entry to correct alphabetical position. Also added anchors to reference/arrays.indexing for glossary references to point to.
|
Thank you, @BvB93, excellent suggestions. One goal of the rewrite was to give more visibility to the reference pages, so this is very welcome. All suggestions incorporated as-is except for the last (#16996 (comment)) -- if the user clicks the Also clarified |
Huh, odd. Does the same issue apply to the |
Sorry, I wasn't clear. The glossary handles both As a result, there's no value in giving |
|
We present at last https://15004-908607-gh.circle-artifacts.com/0/doc/build/html/glossary.html |
|
Nice! |
strctured -> structured, caught by @WarrenWeckesser. Fixed missing language in `view` entry.
|
References to the old Not entirely sure though if we're allowed to straight up remove the old |
|
@WarrenWeckesser -- Thank you! |
|
I think we may be able to pull removal of, maybe discuss it today. But for example debian strips the whole |
Also adding <BLANKLINE>s to some examples for clarity.
doc/source/glossary.rst
Outdated
| array_like | ||
|
|
||
| Any :doc:`scalar <reference/arrays.scalars>` or | ||
| `sequence <https://docs.python.org/3/glossary.html#term-sequence>`_ |
There was a problem hiding this comment.
Can be done in a follow-up, but would be nice to replace these with intersphinx links.
There was a problem hiding this comment.
I wondered if there weren't a better way to handle these. I'm glad to fix it right away. What should it say?
There was a problem hiding this comment.
My guess would be :term:`python:sequence` , but that's only a guess.
There was a problem hiding this comment.
This is a working link, because we have an intersphinx link in conf.py:
:ref:`slice <python:glossary>`
but we want to link to the slice entry, not just the page. This gives "undefined label":
:ref:`slice <python:glossary#term-slice>`
as does this:
:ref:`slice <python:glossary:term:slice>`
When it comes to half-assed, Sphinx is without peer.
Leaving the URLs for now.
There was a problem hiding this comment.
Did my approach fail?
This seems to suggest it should work: https://stackoverflow.com/q/46473481/102441
There was a problem hiding this comment.
I went ahead and swapped all the explicit links using intersphinx in c24bd and 690037.
I'm against duplicating the terms from the Python glossary in NumPy's glossary, as it just leads to more clicks for the user. Nevertheless I switched them to intersphinx links in 6900372 and leave the decision whether to include them to others.
@bjnath a helpful resource for working with intersphinx is to inspect the objects.inv file, which describes the mapping from the sphinx names to URLs. It's not the most visible thing in the world, but the intersphinx docs explain how to grab objects.inv for inspection.
There was a problem hiding this comment.
Did my approach fail?
The approach works as expected! I went ahead and applied it throughout.
There was a problem hiding this comment.
Think I stole the half-assed prize. Sorry @eric-wieser, had the answer right in front of me. Thanks @rossbar for the fixes.
There was a problem hiding this comment.
Also @rossbar thanks for the objects.inv tip.
There was a problem hiding this comment.
I'll write a guide to linking for NumPy docs writers, including stuff like neps and of course this one.
Linking to the Python glossary alerts you that the unfamiliar term isn't NumPy, it's Python, and it takes you directly to the definition. It's easy to imagine technical users who are new to both Python and NumPy. It's a good deed and good documentation to help them sort it out. We can do it adequately with a small number of links. Neither of these sounds better:
Also, could you help me understand this change?
I kept many of the Python terms from the original glossary and perhaps we don't need them all, though it's not clear what harm they do. Why the beef with |
Agreed - I would prefer that we use intersphinx for the terms where they appear. In other words, if in the documentation it says e.g.
It turns out there is no glossary entry for "tuple" in the Python glossary! |
Thanks for explaining this. I'd intended for them to work this way. I will fix it. But we can still keep the Python links to help people who encounter those terms in other NumPy docs.
Two "d'ohs" in a single PR! Thanks for catching this. I did try to check the links but need to do it more effectively. |
|
@rossbar -- So to be clear, your wish is that when a non-glossary file has a Python :term:, it should link directly to the Python glossary rather than to ours? That would be my preference too. A quick grep for :term: doesn't seem to turn up many, or possibly any. Actually most of the :term: links seem silly; they're from files that themselves define the terms; visiting the glossary won't turn up anything that hasn't already been explained in the file. I'd like to fix these, but in another PR. Since there don't seem to be many long-way-around Python links, and the existing Python links might serve a useful purpose, are you OK on leaving the Python links in the glossary? |
Yes, linking directly to the relevant glossary would be preferable.
I don't feel strongly about it - my main concern was with the multiple-redirection problem. If we feel it provides useful context to have stubs in the NumPy glossary to point to the Python glossary then that's fine by me! |
|
I think we are ok with this change which will clear the test failures |
|
CI is passing. I think this is ready to merge. |
| type | ||
| In NumPy, a synonym for :term:`dtype`. For the more general Python | ||
| meaning, :term:`see here. <python:type>` | ||
|
|
There was a problem hiding this comment.
This entry has dissapeared on master, so I removed it from the PR as well. OK?
There was a problem hiding this comment.
This was new content, not meant to be removed. I see I'm author again, so will fix.
|
Merged the master HEAD into this branch and resolved the differences. |
doc/source/glossary.rst
Outdated
| The result of an operation along an :term:`axis` X is an array in which X | ||
| disappears. This can surprise new users expecting the opposite. |
There was a problem hiding this comment.
This description is inaccurate:
>>> x = np.arange(12).reshape(3, 4)
>>> x.shape
(3, 4)
>>> np.sort(x, axis=0).shape # sort along axis 0
(3, 4) # axis didn't disappear!It would be accurate as
| The result of an operation along an :term:`axis` X is an array in which X | |
| disappears. This can surprise new users expecting the opposite. | |
| The result of an reduction along an :term:`axis` X is an array in which X | |
| disappears. This can surprise new users expecting the opposite. |
but I suspect you want this glossary entry to describe the more general case.
There was a problem hiding this comment.
Thanks for pointing this out. Alternative in 511d769 .
eric-wieser
left a comment
There was a problem hiding this comment.
Seems like the merge didn't go cleanly in a few places.
doc/source/glossary.rst
Outdated
| :doc:`numpy.array <reference/generated/numpy.array>` | ||
| is array_like. :: | ||
|
|
||
| >>> a = np.array([[1, 2.0],[0, 0],(1+1j, 3.)]) |
There was a problem hiding this comment.
PEP8
| >>> a = np.array([[1, 2.0],[0, 0],(1+1j, 3.)]) | |
| >>> a = np.array([[1, 2.0], [0, 0], (1+1j, 3.)]) |
doc/source/glossary.rst
Outdated
| >>> x + y | ||
| array([[4, 5], | ||
| [5, 6]]) | ||
| Ordinarily this means the shapes of a and b must be identical. But in |
There was a problem hiding this comment.
| Ordinarily this means the shapes of a and b must be identical. But in | |
| Ordinarily, this means the shapes of a and b must be identical. But in |
There was a problem hiding this comment.
Sentence adverbs usually need the comma:
Frankly, that's impossible.
but in this case it's stylistic:
Ordinarily X is rational; on weekends it's irrational.
Ordinarily, X is rational; on weekends, it's irrational.
and we can imagine a single text having both:
We show that usually X is rational but on weekends it's irrational.
Usually, X is rational, but, on weekends, it is irrational. QED.
There was a problem hiding this comment.
Thanks for giving me the name of this construction.
Both https://www.grammarly.com/blog/commas-after-introductory-words/ and https://theeditorsblog.net/2016/02/21/a-tale-of-adverbs-and-the-comma/ suggest that the comma should be present, so I'd err towards matching the norm rather than flouting stylistic freedom.
There was a problem hiding this comment.
I wouldn't define "norms" based on what's on the internet.
There was a problem hiding this comment.
The guidance given by the Grammarly program (pg88) appears to be:
Introductory clauses and long phrases must always be followed by a comma, while single words and short phrases may or may not.
The second reference doesn't seem to say anything about this case.
Neither one seems to be supporting the comma campaign.
Also added "contiguous," which is referenced in docs but hadn't been defined.
|
Pushed update to address reviewer comments above. Also adds "contiguous," which had not been in the glossary but had a reference in the docs. https://15810-908607-gh.circle-artifacts.com/0/doc/build/html/glossary.html |
eric-wieser
left a comment
There was a problem hiding this comment.
Conflicts look resolved now, thanks.
doc/source/glossary.rst
Outdated
| @@ -37,8 +41,8 @@ Glossary | |||
|
|
|||
| It can be used at most once; ``a[...,0,...]`` raises an :exc:`IndexError`. | |||
There was a problem hiding this comment.
This line needs indenting to fall inside the lost item
doc/source/glossary.rst
Outdated
| [ 7, 6, 5, 4], | ||
| [11, 10, 9, 8]]) | ||
|
|
||
| An operation "along axis 0" behaves as if the argument were an array of |
There was a problem hiding this comment.
This is a nice description. I think you should start with this instead of the reversing example
doc/source/glossary.rst
Outdated
|
|
||
| [1, 4, 2, 5, 3, 6] | ||
| contiguous | ||
| An array is contiguous if it occupies a single unbroken block of memory. |
There was a problem hiding this comment.
Typically the requirement is stronger than this - strides must also be non-negative, with later elements appearing after earlier ones.
doc/source/glossary.rst
Outdated
| A :term:`structured data type` may contain a :term:`ndarray` with its | ||
| own dtype and shape: | ||
| subarray | ||
| An array nested in a :term:`structured data type`: :: |
There was a problem hiding this comment.
| An array nested in a :term:`structured data type`: :: | |
| An array nested in a :term:`structured data type`, as `b` is here:: |
The colon is added automatically by ::, no need to repeat jt
doc/source/glossary.rst
Outdated
| any number of other arrays with different types, shapes, and even | ||
| content. This is much faster than creating those arrays. | ||
|
|
||
| An array created this way is a `view`, and the performance gain often |
There was a problem hiding this comment.
I think this will link to ndarray.view, which isn't really the right meaning.
There was a problem hiding this comment.
It just shows as italic.
doc/source/glossary.rst
Outdated
| every second element of another array:: | ||
| Without changing underlying data, NumPy can make one array masquerade as | ||
| any number of other arrays with different types, shapes, and even | ||
| content. This is much faster than creating those arrays. |
There was a problem hiding this comment.
"content" (at least, in terms of bitpattern) is the the one thing that cant change.
There was a problem hiding this comment.
I'm not sure what I was trying to convey. You're right. Changed in 90111e2 .
doc/source/glossary.rst
Outdated
| Used as a dimension entry, ``-1`` instructs NumPy to choose the length | ||
| that will keep the total number of elements the same. | ||
|
|
||
| >>> np.arange(12).reshape(4,-1).shape |
There was a problem hiding this comment.
| >>> np.arange(12).reshape(4,-1).shape | |
| >>> np.arange(12).reshape(4, -1).shape |
Perhaps also worth linking to the python behavior where a[-1] = a[len(a)-1], and mentioning that applies to axes not just data.
There was a problem hiding this comment.
Added in 90111e2 .
I had great fun trying to get intersphinx to work on the python link. conf.py says
intersphinx_mapping = {
'python': ('https://docs.python.org/dev', None),
and calling
python -m sphinx.ext.intersphinx https://docs.python.org/dev/objects.inv
shows
std:doc
faq/programming Programming FAQ : faq/programming.html
so you'd think
doc:`python:Programming FAQ`
would work. It didn't. Even if it did, it wouldn't link to the relevant entry.
Maybe I missed something. Happy to replace the URL with something Sphinx that works.
There was a problem hiding this comment.
doc:`python:faq/programming` ?
There was a problem hiding this comment.
Of course. It doesn't seem to work with the anchor, though, so we're torn between a politically correct link that leaves you at the top of the page or a politically incorrect link that takes you to what we want you to see.
There was a problem hiding this comment.
I'm not seeing the Sphinx link you're referring to in this diff context.
There was a problem hiding this comment.
Because I chose to keep the link that went directly to the entry, even though it was a URL.
There was a problem hiding this comment.
Using the url looks like the right choice here, unless Sphinx has some hybrid "append this path to the base url of this intersphinx target". Avoiding urls is most important for internal links. For external ones like these, the only danger is linking to an outdated python doc version.
doc/source/glossary.rst
Outdated
| array([[ 0, 1, 2, 3], | ||
| [ 4, 5, 6, 7], | ||
| [ 8, 9, 10, 11]]) | ||
| <BLANKLINE> |
There was a problem hiding this comment.
This looks like a misuse of blankline - numpy does not emit a blank line here.
There was a problem hiding this comment.
It might be misleading if the text were part of a docstring, but here it's used for formatting the documentation and is invisible to the reader.
There was a problem hiding this comment.
Sorry, missed your point initially. Agreed, will change.
|
Are we ready to take the final step and merge this? |
| large arrays. To see the entire array, use `numpy.printoptions` | ||
|
|
||
|
|
||
| ``:`` |
There was a problem hiding this comment.
Any reason for dropping the code formatting?
I'd added the styling for visibility, since the punctuation headings are hard to see. I dropped it since the new theme shrinks the code font, making the headings even harder to see. |
Perhaps " |
Why not, gave it a shot. "(symbol)" overachieves the goal of catching the eye and swallows the symbol. There's no patching up the fact that the monospaced font is too small. I can't think of a compelling rationale for using one format or the other, so I'd like the freedom to pick whatever's easiest to see. |
|
Thanks for trying that out, I agree it looks better as is. |
|
|
||
| **When indexing an array**, shorthand that the missing axes, if they | ||
| exist, are full slices. | ||
| . . . |
There was a problem hiding this comment.
Any reason for the spaces here? That's likely to frustrate users searching for ... on this page.
| . . . | |
| ... |
There was a problem hiding this comment.
Legibility, of course. I thought it more likely that someone would eyeball the glossary for the ellipsis, especially since it's on top of the page, than make the effort of searching with the browser.
Sphinx search doesn't find either version.
Here's how it looks without spaces:
I think the spaces help more users than they hurt.
|
Do any issues remain, or can this be merged? |
|
Let's merge this as-is, and tweak it in subsequent PRs |
|
Thanks @bjnath |
|
And thank you, @mattip, for untangling and re-threading what turned out to be a much more complicated PR than I thought. If you hadn't stepped in I'd still be looking at the pieces like a dazed Ikea purchaser. I appreciate your putting thought and effort into making this merge possible. |
|
And thanks also to reviewers @BvB93 , @WarrenWeckesser, @rossbar, and @eric-wieser! |


Expanded and updated the Glossary page in an effort to make it more useful.
This is a starting place; I welcome the community's comments regarding clarity, choice of entries, length of definitions, technical accuracy, etc.