1.8. Use of custom CSS

This documentation is created using the Sphinx documentation generator which converts the text based markdown source files into the document’s HTML website. The style and layout of the produced HTML is dependent upon the HTML theme in use. For both GDA Developer Guide (this document) and GDA User Guide the theme is configured using the html_theme variable in file gda-documentation.git/common/conf_common.py, it is currently set to use the Read the Docs Sphinx Theme.

As described in the theme’s documentation certain aspects of the theme can be customized using the html_theme_options variable in conf_common.py. To provide additional HTML formatting and functionality the theme’s CSS (Cascading Stylesheets) can be customized. This has been done for the GDA documentation in the file gda-documentation.git/common/_static/custom.css. An introduction to how this works is provided at Adding Custom CSS or JavaScript to Sphinx Documentation.

Below is an overview of the additional formatting and functionality provided by gda-documentation.git/common/_static/custom.css, for full details please view the file directly.

1.8.1. Image display customization

Various modifications can be made to how image files are displayed, e.g. size scaling, visibility and forcing image to be displayed on a newline.

They are used in markdown .md source files by providing alternative text for the image that is recognized by the custom CSS. E.g. to scale an image to fill half the size of the displayed page the following custom CSS is provided:

img[alt=scale50] {
    width:50%;
}

I.e, this will either make the image bigger, if the image size is less than half the page size, or smaller, if the image size is greater than half the page size.

To make use of the above a .md source file would insert an image using:

![scale50](<path_to_image_file>)

Alternatively, if using raw HTML to add hyperlink to diagram the scale directive can be used in the following way:

<a href="<path_to_image_file>">![](<path_to_image_file> "scale50")</a>

For all img[alt=*] directives available see contents of gda-documentation.git/common/_static/custom.css.