Adding image captions

[ccamara]

I am looking for a way to add image captions to slides.

AFAIK, since alt text cannot be rendered, the best solution is to use html's figure and figcaption tags as seen in this SO answer with demo, by doing so we can create a CSS rule in order to theme figure's caption independently.

I have just discovered rst file format, but apparently .. figure: is already accepted (https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#images-and-figures). I tried with that code in hovercraft and worked fine, but unfortunately the output is not what I expected to be and I cannot theme it as I would love.

This is my desired output:

<div  class="step"...>
<figure>
    <img src="image.jpg" alt="alt text" />
    <figcaption>Image caption</figcaption>
</figure>
</div>

And this is hovercraft's output (as you can see figure and figcaption are missing):

<div  class="step"...>
<img src="image.jpg" alt="alt text" width="100%">
Image caption
</div>

Is there any way to modify the figure's output to match the desired one?

[regebro]

RestructuredTexts .. figure:: command predates HTML5, probably by a good decade or two, so it's unsurprising that it doesn't use <figure>. That said it's certainly fixable, but it might need changes in Python I think.

[ccamara]

After reading your reponse I am not sure if my request is out of scope of this repo or not. I am saying this because I have just discovered rst (I was looking for authoring impress.js with markdown and although impress.js allows that I felt that most of the thinks I wanted to do required some more coding than using hovercraft) and I am not sure which parts are done by hovercraft, impress.js and rst/python.

If my request was out of scope of this repo could you please tell me where should I address my request and how that could be used with hovercraft?

[regebro]

Well, it's not out of scope. Perhaps rst itself (docutils) would be a better place to support this HTML5 tags, but I'm not sure. But I won't have much time to spend implementing this at the moment, though, summer is a busy time.

[ccamara]

I have never worked on anything like this, but since you say you are busy and I would really appreciate that feature, could you please give me some guidelines on where to start so I can try to do it myself? (and of course, if I succeed, I will create another PR like the ones that I have already created and are pending for revision)

[ccamara]

Sorry to bother @regebro : could you guide me a while so I can try to fix that for myself? I would really love to use that feature, as I am using plenty of captions that I want to display in a different way than regular text.

[regebro]

I have to admit that it's easier to do than to explain, so I implemented it, and it will be a part of the next release, which will come once I have resolved some more issues.

[ccamara]

Glad to hear that! Thanks!

PS: I learnt how to do it by seeing your commit c18e27cc888f3a3d4bcf48c662871382094f2e6d

[ccamara]

Sorry to ask again, but I've just cloned the repo and executed hovercraft but figure tag is not rendered in html.

This is my rst content:

.. figure:: img/ancient-cities/HSAHARA__1113_42505467.jpg
    :width: 100%
    :align: center
    :alt: alt text
    :figclass: align-center

    Collection: SAHARA Members' Collection. Photographer: Allan T. Kohl

And this is the html output:

<div id="step-19" ...>
<img src="img/ancient-cities/HSAHARA__1113_42505467.jpg" alt="alt text" width="100%">Collection: SAHARA Members' Collection. Photographer: Allan T. Kohl
</div>

As you can see, there are no traces of figure nor figure-caption tags. Am I missing something?

[ccamara]

I'm afraid that's because version 3.0 is not yet released and cannot be installed using pip. Is there any way to install version 3.0 with those changes?

[ccamara]

Ok, I figured it out: maybe it's not the best way to do it (I am pretty new to python and I am learning quite a lot from this project) but I managed to install it by executing sudo python3 install setup.py. After doing so, html is rendering as expected.

[regebro]

Yup, that's it, glad to hear it worked.