Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-16443

RST Guide Example Broken

    Details

      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.

        Attachments

          Issue Links

            Activity

            Hide
            krzys 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
            krzys 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
            jsick 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
            jsick 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
            krzys 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
            krzys 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
            jsick 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.

            Show
            jsick 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
            jsick 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
            jsick 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:
                krzys Krzysztof Findeisen
                Reporter:
                krzys Krzysztof Findeisen
                Reviewers:
                Jonathan Sick
                Watchers:
                Jonathan Sick, Krzysztof Findeisen
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel