CI use numpydoc master when building dev docs #10066
Conversation
I am in favour of using numpydoc dev in PRs as well. Otherwise looking at the PR documentation in CircleCI is not a good indication of what the dev doc is going to look like once the PR is merged. |
Just to be explicit, I think that we should switch to a released numpydoc version as soon as there is one that has the fixes we need. |
|
This also helps test changes in numpydoc which I would like before its release. |
|
Hm using a stable version of numpydoc for releases seems to clash with wanting to test numpydoc dev.... I think we should use the same version of numpydoc for PRs and doc build. I think moving to stable once that works for us would be good, though... I guess it depends on whether we can ensure that the website builds with stable. And testing in multiple versions of numpydoc seems a bit overkill. |
|
Yes, we should move towards stable. But we've never used numpydoc stable until now, and now it's broken for us. So we should be building with something not broken to make sure it is indeed not broken. Merge? |
|
+1 for merge. |
Actually commented too quickly +1 to have numpydoc master always used (so essentially removing the condition |
|
Well let's check this builds before merging then :)
|
Can you remind me the things to check in the generated doc? I seem to remember the Attributes section was not correctly rendered, anything else? |
|
You should consider 0.19 docs as the baseline, because we're still new to
using this repo. still, some of the things that have changed recently in
numpydoc include: display of block descriptions for attributes; parameter
descriptors render as a definition list rather than a series of paragraphs
and blockquotes; the reference number mangling should no longer produce an
absurdly long number
|
|
@jnothman |
|
Yes, I'd noticed too. I'm a bit confused about why it happens (or rather,
why it did not happen before), and think it's somewhat minor, but will look
into it.
…On 13 November 2017 at 21:49, Hanmin Qin ***@***.***> wrote:
@jnothman <https://github.com/jnothman>
Seems that there's still something strange in the dev doc
dev doc:
[image: 2017-11-13_184619]
<https://user-images.githubusercontent.com/12003569/32721893-056bbaf2-c8a3-11e7-90dc-15705d0606e5.jpg>
0.19 doc:
[image: 2017-11-13_184640]
<https://user-images.githubusercontent.com/12003569/32721899-08794214-c8a3-11e7-93e3-d14c784fb8cd.jpg>
There's a broken link for each attribute name and the first line is all
bold.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#10066 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAEz68m33JeD2QXsfMAsMFUcles6GhoCks5s2B6ygaJpZM4QR936>
.
|
|
That comment was with reference to the links.
The first line being all bold is acceptable, IMO. It's the default styling
for a definition list, where previously numpydoc had strangely been using
blockquotes for definitions (hence the excess vertical whitespace in your
second image). We can style it differently if we wish. We could not easily
style it differently before.
|
Only for the current (0.20) cycle have we been relying on the published numpydoc package. As a result we have had to fix a number of issues with numpydoc. I think that, at least for now, we should build the /dev docs with numpydoc master so that we can help test the numpydoc release and its integration here.
I am currently excluding this from PR Circle builds, as I don't want to bother contributors if something fails, but maybe that's unnecessary and we should just use numpydoc master, for now, in all doc builds.