Sphinx 2.0 compatibility issue? #215
Comments
|
does Sphinx 2.0 + numpydoc 0.8.0 work for you, or is that broken as well? |
|
also, can you link to the docstring for |
|
I had been using 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) |
|
The indentation is wrong, you need to de-indent everything from |
|
Okay, thank you! |
|
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. |
|
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 |
|
Yes those docstrings look perfectly fine. Looks like a bigger issue. For now downgrade Sphinx I guess. We'll have to investigate this. |
|
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. |
|
Good to know, thanks. Can't you just |
|
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_themeAfter running your .yml script. Fortunately it looks like they are actively working on this. |
|
I can confirm this, same happens to my projects. |
|
I run a little test with Sphinx 1.8.5 plus numpydoc 0.7.0 looks like this:
Sphinx 1.8.5 plus numpydoc 0.8.0, 0.9.0, and 0.9.1 look like this:
Sphinx 2.0.0 plus numydoc
|
|
This is the test-function I used, copied from numpy/linalg/linalg.py: The whole minimal test-project is here: test.zip, where I built the docs with |
|
It might be that the problem is related to the RTD theme. If I use the default Sphinx-theme, then there is no problem. |
|
FYI I had to add this to Agreed that commenting out |
|
|
|
I tested now |
|
I think this is related to a change in sphinx 2.0 on how they handle field lists in the conversion to html. I saw this in the pandas docs as well (pandas-dev/pandas#26058 (comment)), and already suspected that numpy/scipy will also encounter this shortly, but didn't have the time yet to further investigate. |
|
(I think the difference between 0.7 and 0.8 is due to fixing a bug where
the "definition lists" were in fact rendered as a sequence of <p> and
<blockquote> pairs.)
|
|
As mentionec above by @prisae (#215 (comment)), there seems to be both a change in numpydoc as in sphinx. while with sphinx 2.0, it is now: So before, there was a html table with So even regardless of the numpydoc change, this is something that will need to be updated in custom css (or reported to sphinx, in case this was not intentional) |
|
The issue was correctly identified by @jorisvandenbossche in pandas-dev/pandas#26058 (comment). The styling with the new HTML is a bit tricky, because there are no class labels added by Sphinx that help to disambiguate outer from inner cells etc. |
It seems like @stefanv was saying it didn't fully fix the issue for scikit-image, however if you could create a PR and check that it fixes the original issue reported here, that would be very helpful. |
|
The scikit-image PR from above was eventually merged, so it seems like it's all CSS, and nothing for numydoc to do. |
|
Do we need to document these CSS changes and then close this issue and release? |
|
Not sure that this should be the solution. That would mean that each project, which uses numpydoc, has to manually do a fix in a custom css-style-file? And the ones that fail to realize this will have badly rendered docs? Or did I miss something? |
|
(I see, or maybe each theme, not each numpydoc-user) |
Yes, so it would be more of a compatibility note than user docs. |
|
Great. I just realized that it was fixed in RTD-theme 15 days ago, readthedocs/sphinx_rtd_theme#838 Just tried ( |
Great! @rsokl feel free to try it. Let's leave this open until ...
@jnothman I would say so. Are you up for doing the release or would you prefer someone else do it? I could find time next week. |
|
Neither of us is authorised on pypi? I can't promise much time coming up...
|
|
I can add both of you, please let me know your PyPI username |
|
Eric89GXL on PyPI |
|
added, thanks @larsoner |
|
added |
Can confirm that this works, thanks! |
For anyone looking into it, it's actually And yesterday, they have officially released |
|
Thanks @jaladh-singhal for correcting my typo! Looks like |
|
I am still finding the same abberations in my docs after upgrading Can anyone spot what I am doing wrong here? RTD build log
|
|
Your docs look good to me. What output would you expect? Before the fix, it would have look like Now it looks like: |
|
Ah, I was actually expecting the grey boxes
to be removed. I see that the main issue is indeed fixed now. Thank you! |
|
Indeed, this is just a change with the newer sphinx. The problem was that the |
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!
The text was updated successfully, but these errors were encountered: