# RST Guide Example Broken

XMLWordPrintable

## Details

• Type: Bug
• Status: Done
• Resolution: Done
• Fix Version/s: None
• Component/s:
• Labels:
• Story Points:
1
• Sprint:
AP F18-6
• Team:

## Description

The RestructuredText style guide includes an example for linking to images, but this example works only on local builds because it links to the uningested image. The example should say

  :target: _images/development/docs/lsst_logo.jpg 

which will work on both local and web builds.

## Activity

Hide
Krzysztof Findeisen added a comment -

Re: avoiding _static, what's the alternative? It's at least a pretty conventional location for web content generation systems...

Show
Krzysztof Findeisen added a comment - Re: avoiding _static , what's the alternative? It's at least a pretty conventional location for web content generation systems...
Hide
Jonathan Sick added a comment -

Ok, got it. I hadn't updated the relative link after re-arranging the pages. That's all.

The target in the example can either be

  :target: ../_images/lsst_logo.jpg 

or

  :target: ../_static/development/docs/lsst_logo.jpg 

For a technote, the relative link, as you say, would be to the _images or _static directories.

Show
Jonathan Sick added a comment - Ok, got it. I hadn't updated the relative link after re-arranging the pages. That's all. The target in the example can either be :target: ../_images/lsst_logo.jpg or :target: ../_static/development/docs/lsst_logo.jpg For a technote, the relative link, as you say, would be to the _images or _static directories.
Hide
Krzysztof Findeisen added a comment -

Aha, that's what was going on!

I do still think it's a good idea to use _images instead of _static, because then you're linking from the built site to the built site, and you've got some guarantee that the relative locations will be consistent. With _static that doesn't seem to be the case (though there, in turn, you don't have to think about path squashing).

Show
Krzysztof Findeisen added a comment - Aha, that's what was going on! I do still think it's a good idea to use _images instead of _static , because then you're linking from the built site to the built site, and you've got some guarantee that the relative locations will be consistent. With _static that doesn't seem to be the case (though there, in turn, you don't have to think about path squashing).
Hide
Jonathan Sick added a comment -

Ah, I see what you're getting at.

For example

 .. image:: /_static/development/docs/lsst_logo.jpg  :target: ../_images/lsst_logo.jpg  :alt: LSST Logo 

Becomes

    

(works because its portable)

Using static:

 .. image:: /_static/development/docs/lsst_logo.jpg  :target: ../_static/development/docs/lsst_logo.jpg  :alt: LSST Logo 

becomes

    

(non portable)

Okay, good call on doing a relative link to _images.

Show
Jonathan Sick added a comment - Ah, I see what you're getting at. For example .. image:: /_static/development/docs/lsst_logo.jpg :target: ../_images/lsst_logo.jpg :alt: LSST Logo Becomes <a class="reference external image-reference" href="../_images/lsst_logo.jpg"> <img alt="LSST Logo" src="../_images/lsst_logo.jpg" /> </a> (works because its portable) Using static: .. image:: /_static/development/docs/lsst_logo.jpg :target: ../_static/development/docs/lsst_logo.jpg :alt: LSST Logo becomes <a class="reference external image-reference" href="/_static/development/docs/lsst_logo.jpg"> <img alt="LSST Logo" src="../_images/lsst_logo.jpg" /> </a> (non portable) Okay, good call on doing a relative link to _images .
Hide
Jonathan Sick added a comment -

Sorry I missed this. The update for the image example look good.

Can you also update restructuredtext/examples/figure.rst before merging? Thanks.

Show
Jonathan Sick added a comment - Sorry I missed this. The update for the image example look good. Can you also update restructuredtext/examples/figure.rst before merging? Thanks.

## People

• Assignee:
Krzysztof Findeisen
Reporter:
Krzysztof Findeisen
Reviewers:
Jonathan Sick
Watchers:
Jonathan Sick, Krzysztof Findeisen