DOC: Several documentation fixes (broken links, incorrect sphinx syntax, duplicate sections) #8836

MSeifert04 · 2017-03-25T16:24:26Z

The PR links PyObject references in narrative documentation and also fixes "invalid section header" warning in "linalg.multi_dot" docstring.

It seems weird that :c:type:'PyObject *' can't be resolved as link while :c:type:'PyObject' works. 😕 Is there something wrong in the intersphinx?

(This time with [ci skip])

eric-wieser · 2017-03-25T16:26:49Z

Guessing by :c:func: you mean :c:type:?

MSeifert04 · 2017-03-25T16:31:38Z

you're right, ... corrected.

MSeifert04 · 2017-03-25T16:58:05Z

I'm not sure about the workflow but is it okay to combine several changes (like the one about the invalid section header-warning from numpydoc) and the one fixing (or rather changing) the PyObject *-links? And is the commit message alright?

eric-wieser · 2017-03-25T17:16:00Z

doc/source/user/c-info.beyond-basics.rst

@@ -173,7 +173,7 @@ each array is for PyArray_ITER_NEXT to be called for each of the inputs. This
 incrementing is automatically performed by
 :c:func:`PyArray_MultiIter_NEXT` ( ``obj`` ) macro (which can handle a
 multiterator ``obj`` as either a :c:type:`PyArrayMultiObject *` or a


Does PyArrayMultiObject * work just fine here then? The issue is specifically with intersphinx and not :c:type:somepointer *` in general?

Haha! That's funny because there is no PyArrayMultiObject defined so any link (with or without *) couldn't work. 😄

However from my understanding :c:type::-declared variables can have the * and link correctly. See https://docs.scipy.org/doc/numpy/reference/c-api.array.html#data-type-checking for working PyArrayObject *-link.

eric-wieser · 2017-03-25T17:18:25Z

numpy/linalg/linalg.py

-
-    Example: multiplication costs of different parenthesizations
-    ------------------------------------------------------------
+    Another example: multiplication costs of different parenthesizations.


Not really an example at all - perhaps notes, or more details or something. Perhaps a third-level heading (~~~) under notes instead?

I can also put it in a Notes-section :)

eric-wieser · 2017-03-25T17:18:51Z

I'm not sure about the workflow but is it okay to combine several changes

I'd argue that usually it'd be better not to, but for something like documentation it doesn't really matter

MSeifert04 · 2017-03-25T17:38:14Z

So if I had 10 other documentation-related fixes then it would be fine to amend them? Or will that be hellish to review?

Or should these be seperate commits/PRs?

eric-wieser · 2017-03-25T18:20:10Z

One Pr might be ok, but separate commits might be sensible

eric-wieser · 2017-03-26T15:32:21Z

Regarding PyObject * - I'd rather we fixed something like that upstream, rather than work around it and forget.

…ring. [ci skip]

[ci skip]

MSeifert04 · 2017-03-26T23:21:27Z

@eric-wieser I don't think that's so easy to fix upstream. I'm not sure but there is something weird going on with name-mangling in numpydoc. That's a bit (lot) beyond my current capabilities.

I actually added a lot of additional "link" fixes. I grouped them by the kind of change (should be easy to review commit-by-commit), just let me know if I need to squash them :)

eric-wieser · 2017-03-27T01:56:02Z

That's a bit (lot) beyond my current capabilities.

Yeah, I tryed to debug this and was struggling too. My only concern is that PyObject * is possibly more useful at a glance, and realistically after this change, we'll never switch back if sphinx ever fixes it.

At some point I might try and produce a minimal testcase to file an issue against sphinx

eric-wieser

Great set of fixes - thanks. Few nits.

eric-wieser · 2017-03-27T01:56:56Z

doc/source/reference/c-api.array.rst

@@ -204,7 +204,7 @@ From scratch
    new array is *descr*.

    If *subtype* is of an array subclass instead of the base
-    :c:data:`&PyArray_Type`, then *obj* is the object to pass to
+    :c:data:`&PyArray_Type<PyArray_Type>`, then *obj* is the object to pass to


What happened here before?

It just wasn't rendered as link: https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_NewFromDescr

eric-wieser · 2017-03-27T01:57:57Z

doc/source/reference/c-api.array.rst

@@ -1545,7 +1545,7 @@ Conversion

 .. c:function:: PyObject* PyArray_GetField(PyArrayObject* self, PyArray_Descr* dtype, int offset)

-    Equivalent to :meth:`ndarray.getfield` (*self*, *dtype*, *offset*). Return
+    Equivalent to :meth:`ndarray.getfield<numpy.ndarray.getfield>` (*self*, *dtype*, *offset*). Return


Putting ~numpy. before here doesn't work then?

It would work! But it would render as getfield instead of ndarray.getfield.

[skip ci]

and fixed two broken links because they started with "&". [skip ci]

MSeifert04 · 2017-03-27T11:32:00Z

I addessed some additional issues. However I don't want to make this a "work in progress" so I'll stop now 😄

charris · 2017-03-27T18:05:19Z

doc/source/reference/c-api.types-and-structures.rst

@@ -6,7 +6,7 @@ Python Types and C-Structures

 Several new types are defined in the C-code. Most of these are
 accessible from Python, but a few are not exposed due to their limited
-use. Every new Python type has an associated :c:type:`PyObject *` with an
+use. Every new Python type has an associated :c:type:`PyObject *<PyObject>` with an


I'd rewrite that as "has a pointer to an associated :c:type:PyObject ,,,"? However, I think this whole section is somewhat lacking, what we usually get is a pointer to a PyTypeObject that subclasses the PyObject type. I think it would be better to quote something from the Python documentation.

However, I think this whole section is somewhat lacking

I thought this passage is about the difference between PyLongType and PyLongObject. So to say every python type (long type) has an associated object (long object). I don't quite understand what you mean about every type has a pointer to an associated object?

But I tried to only fix broken links and incorrect attempts to link. Not okay?

A generic PyObject is a C struct that begins with a PyObject (i.e., subclasses PyObject), which in turn is a struct that contains a reference count and a pointer to a PyObjectType struct. I don't know how that fits with the rest of the paragraph 8-)

eric-wieser · 2017-03-27T21:02:31Z

doc/source/reference/internals.code-explanations.rst

@@ -460,12 +460,12 @@ Ufuncs allow other array-like classes to be passed seamlessly through
 the interface in that inputs of a particular class will induce the
 outputs to be of that same class. The mechanism by which this works is
 the following. If any of the inputs are not ndarrays and define the
-:obj:`__array_wrap__` method, then the class with the largest
-:obj:`__array_priority__` attribute determines the type of all the
+:obj:`~numpy.class.__array_wrap__` method, then the class with the largest


What is class referring to here? Is this some weird sphinx feature, or a quick hack? What does this end up linking to?

No, that is actually called class in the numpy documentation on subclassing: numpy.class.__array_wrap__ 😓

Ok, that's pretty weird! Still, I guess if this PR is all about fixing links, then this is the right thing to do

eric-wieser · 2017-03-27T21:03:47Z

But I tried to only fix broken links and incorrect attempts to link. Not okay?

This mostly looks good to me. Thanks for keeping PyObject *and just fixing the links

eric-wieser

I'm sure there's more to do with fixing docs, but as an exercise in fixing links, this looks great.

eric-wieser · 2017-03-27T21:14:10Z

doc/source/reference/c-api.ufunc.rst

@@ -124,9 +122,7 @@ Functions
    :param unused:
        Unused and present for backwards compatibility of the C-API.

-.. c:function:: PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func,
-   void** data, char* types, int ntypes, int nin, int nout, int identity,
-   char* name, char* doc, int unused, char *signature)


Line wrapping is not possible then? Backslashes at EOL?

I haven't checked but c-api.iterator also contains longish lines (>250 chars). I can see what happens with backslashes. Is there a line-length-limit for .rst files?

Backslashes seem to work, should I use them instead?

Yes please!

eric-wieser · 2017-03-27T21:15:52Z

numpy/linalg/linalg.py

-    Example: multiplication costs of different parenthesizations
-    ------------------------------------------------------------
-
+    Notes


We already have a notes section higher up. Best not to have two of them.

Also, the changes to this file kinda feel different to all the rest - maybe put them in their own PR?

maybe I'm blind but I can't find the other Notes-section.

No, it is I who is blind...

I will open another PR for this change then :)

Feel free to leave this in, since it's correct. Just add the backslashes on the lines you unwrapped, and this'll be good to merge

MSeifert04 · 2017-03-27T23:20:13Z

I used EOL-backslashes so the function signature lines wrap at roughly 80 characters.

eric-wieser · 2017-03-27T23:27:29Z

doc/source/user/c-info.ufunc-tutorial.rst

-.. c:function:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func,
-   void** data, char* types, int ntypes, int nin, int nout, int identity,
-   char* name, char* doc, int unused)
+.. c:function:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int unused)


You missed the one that started this conversation!

[skip ci]

MSeifert04 · 2017-03-28T00:31:01Z

sorry, that last change really bloated the "number of lines changed" count.

MSeifert04 · 2017-03-29T20:09:32Z

Anything else that needs to be adressed?

eric-wieser · 2017-03-29T20:49:23Z

If no one else chimes in, I'll merge this tomorrow

charris · 2017-04-01T18:01:29Z

@eric-wieser Merge?

eric-wieser · 2017-04-02T21:12:13Z

Thanks @MSeifert04!

MSeifert04 · 2017-04-03T13:57:40Z

Thanks for reviewing and merging it 👍

I just noticed that the PR has no "component: documentation" tag, I don't know how you do bookkeeping here but maybe it was simply forgotten?

eric-wieser added the 04 - Documentation label Mar 25, 2017

eric-wieser reviewed Mar 25, 2017

View reviewed changes

MSeifert04 added 7 commits March 26, 2017 23:03

DOC: Fix "invalid section header" warning in "linalg.multi_dot" docst…

800160d

…ring. [ci skip]

DOC: Fix "PyObject *" links in narrative documentation

3481194

DOC: include missing second ":" for definitions of types.

8cab060

DOC: fixed link to NPY_END_THREADS

5d315b3

DOC: Included correct destination for "&PyArray_Type" link.

0e2c648

DOC: Corrected links for several __array_*__ functions

74a93ec

DOC: Correct links to ndarray methods when currentmodule != numpy

ea98c96

[ci skip]

MSeifert04 changed the title ~~DOC: Fix links to PyObject and removed invalid section header~~ DOC: Several documentation fixes (broken links, incorrect sphinx syntax, duplicate sections) Mar 26, 2017

eric-wieser reviewed Mar 27, 2017

View reviewed changes

MSeifert04 added 4 commits March 27, 2017 05:39

DOC: Fix broken links (include missing : and capitalization)

1f87e9b

DOC: Function definitions may not extend over several lines

8aea300

DOC: Fixed wrong directive

62ed3b3

[skip ci]

DOC: Replace deprecated (since 1.6) references in documentation

0a1697f

and fixed two broken links because they started with "&". [skip ci]

charris reviewed Mar 27, 2017

View reviewed changes

eric-wieser reviewed Mar 27, 2017

View reviewed changes

eric-wieser approved these changes Mar 27, 2017

View reviewed changes

eric-wieser reviewed Mar 27, 2017

View reviewed changes

DOC: Unwrap long signature lines

5b0e3aa

[skip ci]

eric-wieser merged commit 77eab40 into numpy:master Apr 2, 2017

MSeifert04 deleted the doc_fixed_some_sphinx_warnings branch April 3, 2017 13:57

eric-wieser added the component: documentation label Apr 3, 2017

Uh oh!

DOC: Several documentation fixes (broken links, incorrect sphinx syntax, duplicate sections) #8836

DOC: Several documentation fixes (broken links, incorrect sphinx syntax, duplicate sections) #8836

Uh oh!

Conversation

MSeifert04 commented Mar 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser commented Mar 25, 2017

Uh oh!

MSeifert04 commented Mar 25, 2017

Uh oh!

MSeifert04 commented Mar 25, 2017

Uh oh!

eric-wieser Mar 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eric-wieser commented Mar 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MSeifert04 commented Mar 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser commented Mar 25, 2017

Uh oh!

eric-wieser commented Mar 26, 2017

Uh oh!

MSeifert04 commented Mar 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser commented Mar 27, 2017

Uh oh!

eric-wieser left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MSeifert04 commented Mar 27, 2017

Uh oh!

charris Mar 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MSeifert04 Mar 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eric-wieser commented Mar 27, 2017

Uh oh!

eric-wieser left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MSeifert04 Mar 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MSeifert04 commented Mar 25, 2017 •

edited

Loading

eric-wieser Mar 25, 2017 •

edited

Loading

eric-wieser commented Mar 25, 2017 •

edited

Loading

MSeifert04 commented Mar 25, 2017 •

edited

Loading

MSeifert04 commented Mar 26, 2017 •

edited

Loading

charris Mar 27, 2017 •

edited

Loading

MSeifert04 Mar 27, 2017 •

edited

Loading

eric-wieser left a comment •

edited

Loading

MSeifert04 Mar 27, 2017 •

edited

Loading

eric-wieser Mar 27, 2017 •

edited

Loading

eric-wieser Mar 27, 2017 •

edited

Loading