Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pin nbsphinx to 0.8.6, clean up orphaned resources #6194

Merged
merged 2 commits into from
Oct 11, 2021

Conversation

kevin-bates
Copy link
Member

It turns out that the documentation for Notebook has not been properly producing its Notebook Examples section of its docs. In looking into the issue, it can be reproduced by simply using nbsphinx 0.8.7 (over 0.8.6). However, I suspect there may be more to this than that, but this is a start. This pull request pins nbsphinx to 0.8.6.

While looking into this I noticed the following:

  1. A warning message was produced that docs/source/examples/Notebook/header.md was not listed in any toctree - which is true. However, the contents of that file are already equivalently expressed in docs/source/examples/Notebook/examples_index.rst, so I've removed header.md.
  2. The "Contributing to the Jupyter Notebook" section is a straight include of CONTRIBUTING.rst at the repo root. In that file, a simple verification image is referenced down in docs/source/_static/images. However, while that image will be rendered when viewed from GitHub, the same link is invalid relative to the generated docs. Since the image didn't really provide much information beyond what the text already describes, I chose to remove this image altogether, thereby removing the erroneous link produced in the ReadTheDocs version.

Resolves #6193

@kevin-bates
Copy link
Member Author

Could one of the existing RTD maintainers look at the RTD builds and determine when a second build is always triggered and always fails as a duplicate? If I rebuild the failing build it succeeds - as does the first of the two builds.

Looking at the docs produced, I see all the examples - indicating this PR will resolve the issue, yet the duplicate build failure is preventing (I think) RTD from deeming the build successful.

I've also gone ahead and "activated" the latest release-specific build - having noticed this hasn't happened since 5.x.

cc: @willingc, @blink1073, @Carreau (Sorry you three, but I figured you'd be most likely to respond. 😄 )

@blink1073
Copy link
Member

I think it is due to the multiple webhooks set up: https://readthedocs.org/dashboard/jupyter-notebook/integrations/

@kevin-bates
Copy link
Member Author

Interesting - that seems like a good bet. Looking at the hooks' links, the first appears to get triggered monthly, while the 2nd and third are more frequent (and similar). Can you determine if both the 2nd and 3rd are necessary or how they differ?

@blink1073
Copy link
Member

I'd say remove either 2 or 3, since both appear to be tied to PR builds. That should clear up the duplicate builds. Then, create a test PR and make sure the RTD build is still fired.

@kevin-bates
Copy link
Member Author

Thanks Steve. I've deleted the 2nd webhook and pushed an innocuous change to this PR (hoping this is sufficient to trigger RTD).

@blink1073
Copy link
Member

Seems to be working!

@blink1073
Copy link
Member

(and no duplicate build this time)

@kevin-bates
Copy link
Member Author

Right on. The generated doc looks correct as well (relative to this PR).

@willingc
Copy link
Member

Thanks @kevin-bates I'm going to merge this PR since the Notebook Examples are displaying on RTD now. Thanks @blink1073 too. The JS test failures appear to have existed for a while and are not related to this PR.

@willingc willingc merged commit d564b67 into jupyter:master Oct 11, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Apr 10, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[DOCS] Notebook examples not rendering properly
3 participants