Nbconvert: Troubleshoot build error on RTD

[willingc]

RTD isn't happy with the latest environment.yml changes and nbsphinx or ../. (https://github.com/jupyter/nbconvert/pull/432/files).

cc @michaelpacer P.S. If you create an account on RTD, I will add you as an admin/owner of the RTD instance. Just ping me once it is created 🌻

[mpacer]

@willingc I have one! :) as @mdpacer (an old github handle)

[willingc]

@michaelpacer You now have magic powers!

A 20 second intro to RTD administration (ignore if you already know this)

Advanced Settings Page

As currently set. The conda environment.yml file _should_ override these but YMMV.

In fact, YMMV quite a bit with RTD builds. I don't assume that a failed build means that my configuration is incorrect as sometimes RTD can be a bit stubborn about clearing out old cruft. As such, I set up a test-project for prototyping builds (i.e. willingc/test-nbconvert).

Builds Page

Click on a particular build to find out detail about how it failed.

You may also select a branch from the pull down and start a build.

Versions Page

Be nice to this page. It's your friend.

On this page, you can click "edit" to enable or disable building of a branch.

Clicking the "wipe" button should clear out the cruft of old builds and what not. In practice, that does not always happen especially if RTD pushed changes recently.

My approach is typically the following if a build has failed but I think my code is fine:

• Wipe branch (on versions page)
• Rebuild branch
• Wipe branch, latest, and stable
• Edit branch and disable and submit. Then reenable and submit.
• Take a break and try again in a couple of hours. :sunny:

Versions Main Menu

Versions tab from Admin Menu - does differ from Versions Main Menu

[mpacer]

Thanks for opening that up!

So it looks like adding the ../. line was enough to break the nbsphinx part of the build which is odd. I'll file a bug with them.

That said, I can't find another way to get the environment.yml to have nbconvert appropriately installed.

I think the solution might be to treat the environment.yml as only part of the installation process. Not include nbconvert in it at all. It looks like if we use pip_install: True then we should be be fine and it will automatically treat it as an editable install.

Then we give developers explicit instructions to use pip install . -e if they're building the docs locally.

What do you think?

[willingc]

@michaelpacer Now for the current build errors that I've seen:

• Failing to run setup.py for ../.
• Not finding nbsphinx (I think if we solve the above).

I think that ../. was working locally for me, though I could be wrong. Let me clarify why ../. is in environment.yml to make sure my understanding is correct. It's in there to simply build the latest and most up-to-date changes to nbconvert code base. Correct?

It may be that we need a slightly different strategy for RTD vs. locally. Locally, we can do whatever we like as we can also write a build_docs.sh script. pip install . -e is always fair game as an instruction for developers.

On RTD, they use containers for builds and sometimes this complicates things. I may try to create a requirements.txt file to try with RTD to see if that helps.

Do you have a page in the docs that we can easily view to see if it's building the latest and greatest and what that page should look like? Thanks!

[mpacer]

Now my local build is not working again. But its because of this nbsphinx error, which is deeply confusing me. Its saying that it cannot find it, but it's saying that it is able to install it when I run the conda env create command.

I worry that there may be a broken install that's shadowing this locally but that wouldn't explain the problem with RTD.

You also mentioned at one point doing a local build of RTD, do you think that would help for debugging this?

[mpacer]

Yes, your understanding is correct re: the use of ../..

The build should fail if it is only using nbconvert 4.2.0 because it will try to build the current docs which refer to other (which it was because we had included nbconvert as a dependency in the environment.yml).

[mpacer]

Also, I got the documentation to build locally — though, I still can't figure out what was "wrong" locally.

But, regardless we've still got a problem.

As part of its dependencies, nbsphinx includes nbconvert. So, if we don't actively install nbconvert, it will build the 4.2 version and that will shadow the editable install that occurs by default using the top level rtd yaml.

[mpacer]

Ok…I'm trying to use my fork of nbconvert to test the current solution using a git based pip install (which works locally and can be seen at https://github.com/michaelpacer/nbconvert/tree/doc_improver) but it keeps trying to append a --name argument to the rtd build based on the "build" name which seems to be breaking the ability to install from a environment.yml file.

[willingc]

As part of its dependencies, nbsphinx includes nbconvert. So, if we don't actively install nbconvert, it will build the 4.2 version and that will shadow the editable install that occurs by default using the top level rtd yaml.

Good catch.

[mpacer]

Ok, so I'm getting a strange error

"'/opt/conda/envs/_build_placehold_placehold_placehold_placehold_placehold_placeho' too short in: ncurses-5.9-9
Linking packages ..."

Based on some of the other places where this has come up it might be a conda thing…and so I'm nuking my personal rtd builds because i might have given them too long of a name to manage.

[mpacer]

Edit @willingc Happy to add you as a maintainer on my version of the rtd, is your github handle the same as your rtd handle? yes, your handle is willingc. Confirmed by looking at other repos.

The errors I'm getting are…odd.

But (good news!) the most recent branch of doc_improver builds successfully by swapping in a +git pip build and the order of the nbsphinx vs. nbconvert dependency.

This won't work for the final version I don't think (because we probably don't want the stable docs to be pointing to the master branch repo, but this will be good for the developer version.

When we release, we'll just have to make sure not to deprecate that change in the environment.yml.

In that case, we can just have it point to nbconvert generally for the stable version.

[mpacer]

Does the most recent version of #440 work for you?

[willingc]

Nope. But I think it's a RTD build issue for me not your code. :(

Going to take a break from it for a bit.

[willingc]

@michaelpacer ooh scratch that I didn't see your latest changes. Let me spin that up.

[willingc]

Very, very happy to have merged #440.

Nice work @michaelpacer 📓 🖊 :pencil2: 📔