Using figures in The Turing Way#

We encourage you to use images in The Turing Way book chapters to help readers understand the concpets discussed in the chapter better.

This section of the style guide will explain how to use Markedly Structured Text (MyST) format to add them to the book with appropriate alt text and captions. This is sometimes tricky, refer to the Advanced features and “gotchas” section for troubleshooting.

We are very passionate about ensuring that the creators of the original image files (including you!) are acknowledged appropriately. Please do not use images that are not licenced for reuse.

In this sub-chapter we have used the term figure to refer to an illustration that conveys information in the context of The Turing Way chapters. The term image is used to refer to the file object itself.

Open licence#

Please ensure that you attribute the image files fairly and avoid files that are either restricted from reuse or lack reproduction permissions.

The following recommendations will help you to check that you’re using the images according to their licence permissions:

  • You can source images in the public domain (CC0 licence) or images shared under an appropriate permissive license. Images that are available under CC-BY 4.0 permissions are very easily interoperable with the The Turing Way as this is the same licence as the rest of the content for the book.

  • If you are using your own images, they will be made available under a Creative Commons Attribution 4.0 International (CC BY 4.0) licence as with the rest of the book.

  • If an image (for example that you have found on the internet), is not available under an open licence please contact the original author of the image and seek permission to reproduce their image. Make sure to ask them how they would like to be credited in the caption for the figure.

In general, make sure to always cite the image properly as directed by the image owners. “Image from the internet” is not enough.

Image location, type, size and file name#

Every image file used in this book should be located in the directory book/website/figures of our GitHub Repository. If you use a new image file, please add the file in the figures directory by either uploading via GitHub, or adding locally and pushing the change online when using git.

Please upload .jpg, .png, or .svg files that are under 1MB to allow them to load faster in the online book. If your file is larger than 1MB, please use a local image editing tools, or online tool like IMG2GO to compress your file.

To name your image file, please use all-lowercase and separate words with hyphens (-).

Alternative text#

Alternative text or alt text are used for describing the appearance and function of an image on an HTML page for users who cannot see it. Alt text is often used by visually impaired people who use assistive technology such as the screen readers. Adding alt texts to figures is one of the first principles of web accessibility as it enables the screen reader software to read an alt text to its users helping them understand/explain the content.

If an image link break, alt texts are still functional and read as intended by the assistive technology.

Tip

Apply best practices for describing an image in an alt text.

Writing alt text is all about context. Being aware of how the image is presented and the context in which it sits will give any assistive technology user a better experience. If you’re writing about an image of a painting, you might want to consider if the style of painting is important, does knowing the painter’s name add value? It’s up to you to decide what information is essential.

Here are a few of things to keep in mind when writing alt text:

  • Alt text should be specific and not overly descriptive.

  • Good descriptions are concise, but describe what’s in your images accurately enough to understand their context – imagine you are describing a picture in a just 280 characters.

  • Stay clear of repetition.

  • Never start your alt text with ‘image of’ as this will be obvious to the user.

  • Include any essential text or data that’s part of the visual.

  • Images that already have a caption describing the image, may not need additional alt text.

  • Screen readers will pause and stop when you tell them to but, depending on user settings, might not annunciate exclamation or question marks.

  • Alt text is used by search engines too, so using alt text can help grow a brand’s visibility online.

Source: What’s the alternative? How to write good alt text - Design102. Retrieved from Gov.uk blog Design102 Series. For more information, please refer to Images - Guidance - GOV.UK.

We provide an example of alt text in the section below.

MyST syntax to add a figure to a Turing Way chapter#

All our chapters are written in Markdown files. Therefore, using Markdown syntax to include a figure in a Markdown file will work fine, for example, ![](../../figures/file-collection.*), where the relative path of the image file is provided inside the round brackets ‘()’.

However, this formatting does not allow images to be responsive to screen sizes, making them inaccessible to read on small screens and smartphones. Furthermore, this doesn’t allow authors to resize figures in their chapters or cross reference them somewhere else in the book.

Therefore, our recommendation is to use Markedly Structured Text (MyST) format available in Jupyter Book.

You can resize figures to adjust how they appear in our chapters using the parameters: width and height (takes value in px, for example, 400px) or scale (takes value in percentage, for example, 50%), especially if your original figure is large. Using the parameter: name, you can reference figures in other chapters in a similar manner as defined in Cross-Referencing Sections and Chapters.

The example figure we have use here can be explained with this alt text: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.

All the components of your figure (image file location, size, name, alt text and title) can be encapsulated in section within a markdown file using the following directive:

```{figure} ../../figures/file-collection.*
---
height: 500px
name: file-collection
alt: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.
---
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```

When all these components are used correctly, a figure included in a file will be rendered in the online book like in this page:

Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.

Fig. 123 The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.#

When an image cannot be loaded in a browser or the link to the image breaks, alt text is displayed in place of a figure as shown below:

This example shows when a wrong image path is used, the web browser can't access it and hence does not display correctly.

Please note that a height of 500px works very well with The Turing Way book, but this is only a suggestion.

Caption#

Captions appear below the figure. They should be short and concise and include a reference to the source where they are taken from. In particular it is important to describe the licence under which the image is re-used.

For example, a caption might say:

Making your first pull request on GitHub. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.

The syntax for this image is as follows, and the way it appears in the book is below the code snippet.

```{figure} ../../figures/first-pull-request.*
---
height: 400px
name: first-pull-request
alt: Cartoon-like sketch of two persons sitting across from each other working on their laptops. A straight arrow on the top indicates the main branch of the repository that they are working on, a pull request is shown by a branch coming out of the main arrow labelled as Clone, followed by a Pull Request with the changes that the first person made in the branch, and the final step labelled as Approved that indicates approval of the changes by the second person. This arrow then merges back to the main arrow/repository.
---
Making your first pull request on GitHub.
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
Cartoon-like sketch of two persons sitting across from each other working on their laptops. A straight arrow on the top indicates the main branch of the repository that they are working on, a pull request is shown by a branch coming out of the main arrow labelled as Clone, followed by a Pull Request with the changes that the first person made in the branch, and the final step labelled as Approved that indicates approval of the changes by the second person. This arrow then merges back to the main arrow/repository.

Fig. 124 Making your first pull request on GitHub. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.#

Please make sure that the link to the source is the digital object identifier not the Zenodo record. Also ensure that you have created a link to the source using markdown link formatting: [text](url).

Cross-Referencing Figures in Other Chapters#

After a figure is added in a chapter, it can be referred in other files using the {ref} role like:

{ref}`file-collection`

Advanced features and “gotchas”#

For more advanced parameters, please visit the Jupyter Book Documentation. That page includes information on how to scale and align the figures, and how to add the figures or their captions to the margins of the book.

We’ve noticed a couple of “gotchas” from contributors to The Turing Way and we’ll try to keep this section of the guide up to date for anyone else learning the MyST syntax for figures

  • If things do not work, looking at the deploy log (visible at the beginning of your PR) might well give you hints about the issues are.

  • Figure path are case-sensitive, make sure the name of the file is all lowercase

  • name: is for including in reference links, it cannot have spaces

  • The path to the figure will depend on the position of the .md file in the repo (one or two folders away from website will give ../ or ../../ respectively.

  • You can choose to include the file extension with your path, or you can use the format path/filename.* to allow Jupyter Book to decide which file to use in the case that multiple filetypes with the same name exist. Jupyter Book will choose the one most appropriate to the intended output. This is useful as it means that filetypes can be changed without breaking the pages that use those files.

  • You cannot have line breaks in the alt text, but you can have it in the caption.

  • Both : and " have syntactic meaning for Sphinx. That means it is important that you do not use these characters in your alt text.