Correction of some formatting and image alias errors
I'm not sure where to put this information for now, but here's what I corrected. To be added to some sort of guide later.
-
There must be some spaces before the
:alt:
line, at least so that it lines up with the|
above it- We use 4 "tabs" (hit the "tab" key four times) by convention and so that it lines up nicely
- The important part is that it must be more indented than the
..
which indicates that what follows in a comment - If the
:alt:
line is less indented than the..
, Sphinx will consider it as normal text (and since the images.rst file is used in all pages, that line of text will appear on all pages)
-
When updating screenshots, if we change the alias in the images.rst file (the part inside the vertical bars, i.e.
|alias|
), it's important to change it in all pages where that image appears- Personally, I use the command
git grep
to find all occurrences of the alias in all the pages. Most images are only used once, but some are used more than once. - So if we change
|image123|
to|something|
in images.rst it's important to change|image123|
to|something|
in every page where that image appears - It's important to change the alias in the page for the same alias that is in images.rst. So if we change
|image123|
to|something|
in images.rst it's important to use exactly|something|
in the page as well not|image of something|
or some other text.
- Personally, I use the command
-
In images.rst we use the file name as the alias. This is by convention in our project. It makes it easier to remember what the alias is.
The format is
.. |filename| image:: images/directory/filename.png
:alt: Alternate text
And in the page, the format is
|filename|