Nbconvert: Correct two warnings when building docs

[willingc]

Currently, docs do build, but two warnings are generated when building the api docs. The root cause appears to be documenting get_exporter in source/api/exporters.rst. When commented out, the first warning is gone. Though, the second warning remains. Commenting out init_single_notebook_resources in source/api/nbconvertapp.rst removes the second warning. Need to investigate why they are warning when not commented out.

Warnings

reading sources... [100%] usage

/Users/carol/code/jupyter-projects/nbconvert/docs/source/api/exporters.rst:13: WARNING: autodoc: failed to import function 'get_exporter' from module 'nbconvert.exporters'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/carol/anaconda/lib/python3.5/site-packages/Sphinx-1.4.1-py3.5.egg/sphinx/util/inspect.py", line 109, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: module 'nbconvert.exporters' has no attribute 'get_exporter'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/carol/anaconda/lib/python3.5/site-packages/Sphinx-1.4.1-py3.5.egg/sphinx/ext/autodoc.py", line 514, in import_object
    obj = self.get_attr(obj, part)
  File "/Users/carol/anaconda/lib/python3.5/site-packages/Sphinx-1.4.1-py3.5.egg/sphinx/ext/autodoc.py", line 410, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/Users/carol/anaconda/lib/python3.5/site-packages/Sphinx-1.4.1-py3.5.egg/sphinx/util/inspect.py", line 115, in safe_getattr
    raise AttributeError(name)
AttributeError: get_exporter
/Users/carol/anaconda/lib/python3.5/site-packages/nbconvert/nbconvertapp.py:docstring of nbconvert.nbconvertapp.NbConvertApp.init_single_notebook_resources:7: ERROR: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done

[mpacer]

That's really odd given that it doesn't err on export or get_export_names and if you interactively try to access nbconvert.exporters.get_exporter it works just fine.

[mpacer]

That is, I was worried that for some reason stuff from the __all__ commands wasn't percolating up due to a typo or something that I couldn't detect visually… but it doesn't look like that's the problem in any way.

[willingc]

Opening up a WIP pr that fixes the autodoc of the get_exporter.

Still trying to sleuth the other warning.

[willingc]

if you interactively try to access nbconvert.exporters.get_exporter it works just fine

Hmm...I tried earlier to do an interactive help(nbconvert.exporters.get_exporter) and it didn't work for me.

[mpacer]

Edit:
Hmmm… ok. I think it's a python2/3 error.

I can't figure out what is causing it but it works when I'm in python3 but not in python2.

So I don't know how you're getting that error. I've now made sure that my python2 dev environment also points to 5.0.0dev and now that I did that, help(nbconvert.exporters.get_exporter) works.

[willingc]

Hmm...I usually work in 3 so I will test both on the plane tomorrow. In the meanwhile, it could be a funky Python namespace thing.

[mpacer]

Is there any chance that sphinx could be accessing nbconvert 4.2 and not nbconvert 5.0.0dev?

[willingc]

Bingo! Yup it's nbconvert 4.2. I used the conda environment.yml file from the repo, but (ugh!) neglected to run python3 setup.py develop. All cool now.

I'm going to leave the issue open so that I remember to document that step in the instructions. Also I think the environment.yml is missing entrypoints package.

[mpacer]

Re: entrypoints doesn't seem to be missing: https://github.com/jupyter/nbconvert/blob/master/docs/environment.yml#L12

I'm not sure I fully follow, but I look forward to reading more.

[mpacer]

Did we fix this a while back?

[mpacer]

Specifically via #440?

[willingc]

I think so. FWIW, I recently switched the jupyterhub docs back to a requirements.txt/pip instead of conda since the conda builds were not clearing properly on rtd. Feel free to close this. We can always open something new when/if needed.

[mpacer]

@willingc I'm a little confused. When I look at the Jupyter docs at the readthedocs.yml file it looks like it's still using conda and not pip: https://github.com/jupyterhub/jupyterhub/blob/master/readthedocs.yml.

(since its short I'll quote it here)

name: jupyterhub
type: sphinx
conda:
    file: docs/environment.yml
python:
    version: 3

[mpacer]

Also, when I look at the latest build it seems to be using conda to setup its environment, not pip and requirements.txt: https://readthedocs.org/projects/jupyterhub/builds/4505307/.

[willingc]

My user experience is that if you set the advanced options in RTD to use requirements.txt that has higher build priority than the rtd.yml file. I've been trying to find time to troubleshoot the rtd build system or at least set up a build system. However, it won't happen until the other side of Grace Hopper :D

[willingc]

@michaelpacer Scratch what I just said. You are in fact correct that it is building with conda. It wasn't building the other day on my test instance https://readthedocs.org/projects/test-jupyterhub/builds/4496874/ and I didn't go back to check that it was. I stand corrected today it looks as if the rtd.yml trumps rtd's site settings. Software {insert shrug emoji here}. Great catch by the way.

[mpacer]

I only caught it because I was going to try to help with the build :).

Ah! I still am confused by that build error…but I worry that it might be related to the _name_ of your rtd build. How I figured even _that_ much out is a long story…but suffice it to say that I found that shortening my rtd build title was sufficient to get around the ncurses placeholder error. In analogy the solution would be something like test-jupyterhub → t-jupyterhub. I still have a hard time believing that that worked, but it did. I don't remember if I also had those LOCKERRORs.

Regardless, I'm happy that its not turning out to be a problem! Because other than that trick I am not sure how to fix that. There are a few issues in github repos with a similar error, but it was unclear how they relate to the rtd problem and all the solutions wouldn't apply to the case where our hands are as tied as they are with rtd.

Aside: I know it's recent, but I'm sad/surprised that webfonts haven't been updated to support Unicode 9.0 emoji like: 🤷