Doc build fails if IPython is installed system-wide

[hroncok]

Hi, I'm trying to update the Fedora RPM package to 5.0.0. Part of the package build process is rebuilding the docs.

When the documentation of notebook-5.0.0 is built, the notebook file docs/source/examples/Notebook/Importing Notebooks.ipynb is evaluated and the following code is run:

import shutil
from IPython.paths import get_ipython_package_dir

utils = os.path.join(get_ipython_package_dir(), 'utils')
shutil.copy(os.path.join("nbpackage", "mynotebook.ipynb"),
            os.path.join(utils, "inside_ipython.ipynb")
)

This of course fails when run under non-root user and IPython is installed system-wide:

PermissionError: [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/IPython/utils/inside_ipython.ipynb'

You can ignore this error by setting the following in conf.py:

    nbsphinx_allow_errors = True

As a workaround I can use suggested nbsphinx_allow_errors = True, but that may be dangerous as it is set globally, not just for this one file. I'm not yet sure what it does exactly, but the docs might end up rendered with error, so I's rather not use it at all.

What is a benefit of this particular example (putting a notebook inside an existing, already installed module)? Can this section be removed form that example file? (I'll probably end up patching it out in Fedora, as it would never work for regular user anyway, but would rather make it an upstream change.) Thanks.

[takluyver]

Thanks for the packaging work :-)

It's not particularly important that that example runs - it's demonstrating a little-used tool for importing notebooks as Python modules, and it's doing that to show that you can put a notebook into a standard Python package and import it just like if it was a .py file.

[hroncok]

It's not particularly important that that example runs

In that case, is there a mechanism to enable nbsphinx_allow_errors just for that one file? Because I don't know any.

[takluyver]

Yep:

• http://nbsphinx.readthedocs.io/en/0.2.13/never-execute.html
• http://nbsphinx.readthedocs.io/en/0.2.13/allow-errors.html

[hroncok]

Cool, thanks. Would allowing errors in this particular notebook be accepted in a PR?

[hroncok]

Note that that would still generate docs with an exception and a little change would be needed in the text, something like "This only works if IPython is installed in a place where we can alter it."

[takluyver]

I think I'd prefer to build the docs without executing that notebook at all, rather than allowing the error - see the first of the two links I posted above.

[hroncok]

That would fix the issue as well.