Symbolic link causes problems with images in output cells

[twiecki]

For example: http://pymc-devs.github.io/pymc3/notebooks/BEST.html
Tries to link to: http://pymc-devs.github.io/pymc3/notebooks/_build/doctrees/nbsphinx/notebooks_BEST_8_0.png

During compilation I get many warnings like:
/home/wiecki/working/projects/pymc/docs/source/notebooks/survival_analysis.ipynb:193: WARNING: image file not readable: notebooks/../_build/doctrees/nbsphinx/notebooks_survival_analysis_11_0.png

I have seen #9 which looks very related and installed from master to make sure #10 was included but those don't fix this issue.

[springcoil]

No idea how to debug that - do you want to merge WIP already or wait for the fix?

[mgeier]

I don't think #9 and #10 have anything to do with that.

The problem seems to be that when Sphinx reads the intermediate reST file, which contains image links in the form notebooks/../_build/doctrees/nbsphinx/*.png, it apparently doesn't follow the symlink back to the source directory but it applies the .. to the symlink-free original location on the file system (which would actually make sense if this were in a real reST file). Therefore, it doesn't find the intermediate directory where the image files are stored.

This will hopefully be solved with #36, but I'm afraid this won't happen very soon.

In the meantime I guess I'll have to make some kind of work-around, any ideas how to tackle this?

[mgeier]

Correction: The intermediate reST file contains links like this: ../_build/doctrees/nbsphinx/*.png, but Sphinx somehow prepends the directory notebooks/, which contains the source file.
I guess it's actually the operating system that resolves the .. part.

[mgeier]

Let me throw in a few random links:
https://unix.stackexchange.com/questions/83966/cp-somefile-copies-to-a-different-directory-after-cding-via-a-symbolic-link
http://superuser.com/questions/749750/how-to-maintain-parent-path-of-symlinked-folder
http://stackoverflow.com/questions/10456784/behavior-of-cd-bash-on-symbolic-links

[twiecki]

It seemed to ultimately work in #9, what is different about my usecase? Would it help if I moved the NBs out of the subdirectory? The same problem persists locally.

[mgeier]

The problem is the symbolic link. It should work if you actually move the files to a "real" subdirectory docs/source/notebooks/. If you want, you can then make a symbolic link in the other direction, back to the original place pymc3/examples/notebooks/.

[twiecki]

Oh nice, that works. http://pymc-devs.github.io/pymc3/notebooks/stochastic_volatility.html. Thanks.

[mgeier]

Good to know that the work-around helps. I changed the title to mention that the problem occurs in output cells. There shouldn't be any problems with images in Markdown cells.

[twiecki]

Any solution to this? Having the NB directory live in the doc subdir is a bit unwieldy.

[mgeier]

Sorry, I don't know how to solve this before #36. But I'm open to suggestions!

If you don't want to move the NB dir into the doc dir, you can do it the other way round, by moving conf.py to your main directory (and then use master_doc = 'doc/index'). Would this be less unwieldy?

[twiecki]

Thanks for the suggestion. conf.py as well as Makefile, right?

[mgeier]

The Makefile is optional and IMHO not necessary. But if you want to use the auto-generated Makefile as is, I guess you'll have to move it, too. But I don't think that's a good idea since people might think that's a Makefile for the whole program/library, not only for the docs.

You could of course create a custom Makefile and put it anywhere you want, or you could manually call sphinx-build every time, or create a simple shell script, or ...

The IMHO nicest solution would be to use BuildDoc in your setup.py, then you could generate the docs by simply running:

python3 setup.py build_sphinx

In this case, you wouldn't even need to move your conf.py, since you could specify its location in setup.py.

If you want to go that way and need more information, don't hesitate to ask.

[twiecki]

Thanks @mgeier. I think I'm making some progress: pymc-devs/pymc#1245

The problem is that build/sphinx directory where the compiled docs get stored does not contain index.html and the other master level files in the root directory but build/sphinx/html/docs/source. Any idea on how to fix that?

[mgeier]

I didn't think about this before, but I guess it makes sense that the output directory is laid out like this (mirroring the source directory).

You could try to move index.rst to the main directory, too, but at some point it will get crowded ...

To get nicer URLs for the other pages, you should probably get rid of the sources/ subdirectory.

[johannes-mueller]

It works for me when I create a real directory notebooks/ in the sources/ subdirectory and in there have symlinks to the individual notebooks.

I think that's a feasible workaround.