GitHub noob question: How do I attach/link/upload a picture to my PR?

ESPHome
1

I’m trying to create my first PR, a new part in the cookbook section.
I have created the new .rst file, but I can’t find out how to attach my picture that I have locally on my computer. Where and how do I upload that together with the document file?

I’m reading the Contributing to esphome-docs guide but can’t find anything about it.

I have tried to upload my pulses.png to esphome-docs/images/ in my forked repository, but that didn’t work. I got the same error.
What have I missed?

From my .rst file:

Pulse Catcher
=============

.. seo::
    :description: Example to use the pulse meter sensor as a pulse catcher.
    :image: pulses.png

Error during building:

Sphinx parallel build error:
ValueError: File /home/runner/work/esphome-docs/esphome-docs/images/pulses.png for seo tag does not exist <document source="/home/runner/work/esphome-docs/esphome-docs/cookbook/pulse-catcher.rst"><section ids="pulse-catcher" names="pulse\ catcher"><title>Pulse Catcher</title></section></document>
make: *** [Makefile:21: html-strict] Error 2
reading sources... [  6%] automations/actions .. changelog/2024.6.0
Error: Process completed with exit code 2.
2

Looking at the others in the repo, your image needs to go to the images folder (in the cookbook folder) and you need to reference it there (not in the same cookbook folder like your rst file is doing now). You also need to add that file to git so it will be part of your PR.

3

Yes, I have also looked at other stuff in the cookbook section and found the image folder.
I have copied the content from an existing cookbook .rst file and modified it to get the structure (and hopefully the paths?) correct, but I don’t understand what to do with the image…

I believe this could be the key here, right? Are you able to guide me a little bit more how to to that, please.

4

Not sure what you mean by “upload”. When working with git you add files, then commit, then push.

With the docs, the best way to determine how to do something is look at other examples. So for your case, look at another file using the seo tag, then find out where in the file tree the referenced image is placed. Use that same pattern for your file.

Use the make live-html and make html-strict commands to preview and check your changes locally.

Make sure you have added and commited all your files - use the git status command to check for any files not included. Make sure you do git commit and git push after adding all required files.

If the GitHub CI build fails, but it works locally, it’s likely you have not added a file.

1 Like