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
.
1.8.2. Hyper-links to external sites¶
To make hyperlinks to various external sites more visible in the documentation the custom CSS provides various formatting of links based upon the contents of the URL they are linking to. This is done for links to Diamond Confluence, Gerrit, GitHub, Javadoc and SourceForge (see External links to source code documentation).
E.g. the CSS that styles Gerrit links is:
/* Modify links to Gerrit to make them more easily recognisable */
a[href*="gerrit.diamond"] {
font-size: 14px;
font-family: mono;
background: url('icon-gerrit.png') no-repeat 100% 0;
background-size: 16px 16px;
padding-right: 19px;
border-bottom: 1px solid;
}
Thus, a .md
source file that contains:
[gda-documentation](https://gerrit.diamond.ac.uk/admin/repos/gda/gda-documentation)
Will have the link rendered in HTML as gda-documentation.
To not obscure this formatting it is important the writer of the markdown
does not use any additional formatting that might obscure that being added
by the CSS, e.g. don’t use monospace
, but bold and italics are fine.
Similar CSS is used to provide highlighting to images that are also links, by adding a link finger icon at the side of the image, and for auto-generated class and sequence diagrams by adding an orange border (see Auto generation of Class and Sequence diagrams).