relative image paths work locally, but not in online docs (github pages)

[Moritz Lürig]

My project looks like this:

proj ==> root dir
proj/docs ==> sphinx build dir

proj/assets ==> images 

https://github.com/mluerig/phenopype ==> repo

https://mluerig.github.io/phenopype/ ==> docs

https://mluerig.github.io/phenopype/tutorial_2_phenopype_workflow.html ==> converted jupyter notebooks

Problem: I use relative paths in html tags to add images to my documentation:

<img src="../assets/figures/header.png">

The images are stored in the assets folder in the root directory, from which they are also accessed by jupyter notebook and the repo-readme. 

Now when i build my docs locally, everything works fine, relative paths work, but when I push them to the repo (and the github pages), I get broken links. I tried a bunch of things, e.g. adding this to conf.py:

sys.path.insert(0, os.path.abspath('../../'))


I don't know why it's working locally, but not online - does anyone know where the problem lies?

[Moritz Lürig]

I fixed it by using an image folder INSIDE the docs directory. 

Can sphinx not source files from the project directory level? Maybe I got the relative paths wrong...

[Stefano David]

On Wednesday, 25 March 2020 12:16:35 UTC+1, Moritz Lürig wrote:

My project looks like this:

proj ==> root dir
proj/docs ==> sphinx build dir

proj/assets ==> images 

https://github.com/mluerig/phenopype ==> repo

https://mluerig.github.io/phenopype/ ==> docs

https://mluerig.github.io/phenopype/tutorial_2_phenopype_workflow.html ==> converted jupyter notebooks

Problem: I use relative paths in html tags to add images to my documentation:

<img src="../assets/figures/header.png">

If you add figures properly using figure:: or image:: you should just write e.g.,

.. image:: /asset/figures/header.png

But looking quickly at your repo, all images are included via raw:: html, so my guess is that this is not sphinx's fault, but that the /assets/ directory is not correctly rechable from the place where the final html is located.

my 2 cents,

Stefano

[Moritz Lürig]

Thanks, Stefano.

I guess some confusion on my side arises from Sphinx behavior to copy images to an "_images" folder inside the docs folder. Because I am using multiple source directories (using `sphinx-multibuild`) and also jupyter notebooks converted to html (using `nbsphinx`) I am trying to avoid multiple locations at which the images are stored. Therefore, my original question remains: why to relative paths work locally, but not online? I.e. having a central "assets" works locally, but not online - is that because if github pages are specified to be in the docs folder of the master branch, they cannot go beyond that level?

[Stefano David]

Hi Moritz,

On Monday, 30 March 2020 11:30:13 UTC+2, Moritz Lürig wrote:

Thanks, Stefano.

I guess some confusion on my side arises from Sphinx behavior to copy images to an "_images" folder inside the docs folder. Because I am using multiple source directories (using `sphinx-multibuild`) and also jupyter notebooks converted to html (using `nbsphinx`) I am trying to avoid multiple locations at which the images are stored. Therefore, my original question remains: why to relative paths work locally, but not online? I.e. having a central "assets" works locally, but not online - is that because if github pages are specified to be in the docs folder of the master branch, they cannot go beyond that level?

Yes, images by default end up in build/_images, so you should build your raw HTML code to point to that directory, but I understood you already did this.

About relative paths and content "outside" the source folder: I use withouth problems symlink to deal with this. I have different documents in a same repository, each in a separate directory which is also a separate source folders, but I also have some common content for both projects and extensions I use for both of them. So I put the files for this in a separate directory (call it "common") and I successfully use symlinks to access content in "common". I do not know, however, if this is a feasible approach or if it should be avoided. In the latter case, I'd be happy to accept suggestions.

Hope this helps,

Stefano

[Moritz Lürig]

Thanks Stefano. I have never used symlinks before - do you have a public repo I could have a look at, or point me towards instructions on how I would do that?

I don't know about your reason for avoiding duplicate files, but I really would like to make the repo as light as possible. Currently the files in my docs folder make ~60% of the whole repo size, and having all images as duplicates inside docs/_images doesn't help

[Stefano David]

Hi Moritz,

On Tuesday, 31 March 2020 13:53:12 UTC+2, Moritz Lürig wrote:

Thanks Stefano. I have never used symlinks before - do you have a public repo I could have a look at, or point me towards instructions on how I would do that?

I don't know about your reason for avoiding duplicate files, but I really would like to make the repo as light as possible. Currently the files in my docs folder make ~60% of the whole repo size, and having all images as duplicates inside docs/_images doesn't help

It took a bit long, sorry but I am quite busy this time. I set up an example github repo that showcases the use of symlinks. I assume it is safe to publish it here, so, here's the link: https://github.com/stefanodavid/potential-octo-engine Feel free to fork it and play with it.

About the reason for using symlink and avoid duplicate files, the main (but not the only one) reason is maintenance: if there is some duplicated content (e.g. description of a feature), you change it in one place and you're done, insteave of having to remember where the same content is located. When you deal with complex projects, it is almost inevitable that you try to save your time for new content that for maintenance of existing code.

Best regards,

Stefano

[Moritz Lürig]

Hi Stefano, 

thanks so much, I will have a look soon (sorry I'm quite busy at the moment).

Cheers
Moritz