Sphinx 2.0 compatibility issue?

[rsokl]

My readthedocs project has started failing to render my docs according to the numpydoc (v0.9.1) layout.

---

E.g. this is how my docs looked a couple of months ago:

---

And now my docs build to this:

---

It appears that this is concurrent with RTD upgrading its sphinx version from 1.8 to 2.0. Is this possibly the culprit? I am not sure how best to proceed in debugging this, so any guidance would be very much appreciated!

[rgommers]

does Sphinx 2.0 + numpydoc 0.8.0 work for you, or is that broken as well?

[rgommers]

also, can you link to the docstring for mygrad.add or paste it here?

[rsokl]

I had been using numpydoc 0.8.0 and that version broke. I tried upgrading to 0.9.1, and saw no difference.

Here is the docstring:

def add(a, b, constant=False):
    """ ``f(a, b) -> a + b``

        Parameters
        ----------
        a : array_like

        b : array_like

        constant : bool, optional(default=False)
            If ``True``, the returned tensor is a constant (it
            does not back-propagate a gradient)

        Returns
        -------
        mygrad.Tensor
        
        Examples
        --------
        >>> import mygrad as mg
        >>> mg.add(1.0, 4.0)
        Tensor(5.0)
        >>> x1 = mg.arange(9.0).reshape((3, 3))
        >>> x2 = mg.arange(3.0)
        >>> mg.add(x1, x2)  # equivalent to `x1 + x2`
        Tensor([[  0.,   2.,   4.],
                [  3.,   5.,   7.],
                [  6.,   8.,  10.]])"""
    return Tensor._op(Add, a, b, constant=constant)

[rgommers]

The indentation is wrong, you need to de-indent everything from Parameters onwards by 4 spaces. That should fix it. Sphinx probably started processing indentation a little differently.

[rsokl]

Okay, thank you!

[rgommers]

I'll close this issue, because I don't think we can or want to add a workaround for this. If there's something else that's off please keep commenting or open a new issue of course.

[rsokl]

Actually, I think indentation may not be the case. This function has the correct indentation level, and yet it still fails to render properly.

Edit: here is another docstring with proper indentation, but that fails to render

[rgommers]

Yes those docstrings look perfectly fine. Looks like a bigger issue.

For now downgrade Sphinx I guess. We'll have to investigate this.

[rsokl]

Unfortunately I have to use conda to build my RTD environment, and there is no way to keep RTD from overwriting my version of sphinx during their pip install for now.

Obviously this is an issue with RTD, and not numpydocs. But I might as well make note of it here in case others come here with the same issue.

[rgommers]

Good to know, thanks. Can't you just conda install pip and then pip install sphinx==1.8.5 --force or something like that?

[rsokl]

Unfortunately, no. They made a strange decision when it came to the conda pipeline, and run, rain or shine:

conda install --yes --quiet --name latest mock pillow sphinx sphinx_rtd_theme

After running your .yml script. Fortunately it looks like they are actively working on this.