search

mli / new-docs

https://beta.mxnet.io/
13 stars 17 forks source link

Hosting Images on Site #87

Open thomelane opened 5 years ago

thomelane commented 5 years ago

Can't seem to host images on the website. Solution might be to add a step to the Makefile to copy across images. @astonzhang how are you handling this on the D2L site?

astonzhang commented 5 years ago

@aaronmarkham have we resolved this issue yet?

astonzhang commented 5 years ago

Yes, on D2L we copy images in Makefile.

thomelane commented 5 years ago

thanks @astonzhang, couldn't find any specific reference to images though. Are you just copying all file types as part of this line? We're going to be placing images in the same directory as the guide, since this is the easiest to maintain so we'll need to add something a bit different in our Makefile.

thomelane commented 5 years ago

So far I have a command that copies image and video content into the build directory (working on MacOS and Ubuntu) that can be used in the Makefile:

rsync -arv --prune-empty-dirs --include "*/"  --include="*.png" --include="*.jpeg" --include="*.jpg" --exclude="*" "./guide/" "./build/_build/html/guide"

And a web server that serves images (python -m http.server doesn't by default). Just installed twisted and ran using:

sudo apt-get install python-twisted-web
twistd -no web --path=build/_build/html --port tcp:8000

So images are hosted at the correct location. Only thing left to fix is the path to the images from the html files. ![alt](./imgs/NCHW_BN.png) in the markdown gets converted to http://localhost:8000/guide/packages/gluon/normalization/guide/packages/gluon/normalization/imgs/NTC_IN.png instead of http://localhost:8000/guide/packages/gluon/normalization/imgs/NTC_IN.png. Any ideas on this one @aaronmarkham?

aaronmarkham commented 5 years ago

I think you want this instead:

rsync -arv --prune-empty-dirs --include "*/"  --include="*.png" --include="*.jpeg" --include="*.jpg" --exclude="*" "./guide/" "./build/guide"

I wouldn't put anything in _build as that's the output directory for Sphinx. It should find what you have in /build/ and use that to transform to html and deposit it in the _build/html folder.

thomelane commented 5 years ago

Still a lot of mess to sort out here. I have both images and video showing with the following.

1) Make sure all markdown images have unique descriptions (e.g. ![description](./path/to/image.png)). Without this strange things happened, and I ended up with all images being replaced with the same image (i.e. don't use blank description like ![](./path/to/image.png))

2) Copy images to ./build/guide using...

rsync -arv --prune-empty-dirs --include "*/"  --include="*.png" --include="*.jpeg" --include="*.jpg" --exclude="*" "./guide/" "./build/guide"

3) make EVAL=0

4) Copy video to the _build directory since references in HTML tags (e.g. <video>) aren't modified, and don't move across correctly. Might also need this for images that are referenced using <img> tag in the markdown.

rsync -arv --prune-empty-dirs --include "*/"  --include="*.mp4" --exclude="*" "./guide/" "./build/_build/html/guide"

5) Serve with web server that supports images

twistd -no web --path=build/_build/html --port tcp:8000
thomelane commented 5 years ago

Sure there must be a better way to get around Step 4 there.

aaronmarkham commented 5 years ago

Sure there must be a better way to get around Step 4 there.

Host videos elsewhere? I'm not sure adding mp4s to the repo is a good idea.

thomelane commented 5 years ago

Could do, but these videos are tiny. About the same as an images and we're including them in the repo for simplicity. As an example... https://github.com/mli/new-docs/blob/master/python/guide/packages/autograd/imgs/autograd_graph.mp4

aaronmarkham commented 5 years ago

Ya, that makes sense. This is from an old forum post... sounds like it would work: ... For local video files, you can use .. raw:: html directive.

  1. Put video files into _static directory
  2. write