Add How-to guide for README images

docs/how-to/readme-images.md

@@ -0,0 +1,110 @@
+# How to add images to the README
+
+The contents of the `README.md` file may be presented in various places:
+
+* Project homepage on GitHub
+* Project documentation (if using Sphinx build)
+* PyPI (if publishing there)
+
+This places some limitations on including relative content as PyPI is only
+provided with the content directly in `README.md` and not the surrounding
+resources.
+
+Additionally the Sphinx build uses the `docs` directory as the root of the build
+meaning that included content is relative to that path.
+
+A reference link in Markdown syntax can be used to allow images to be included
+such that  a fixed image URL is used in the `README.md` itself which can be
+overridden to a relative URL for the Sphinx build. This satisfies the three use
+cases above.
+
+Example of Markdown reference link:
+
+```markdown
+![Image alt text][reference]
+```
+with the `reference` defined (potentially elsewhere) as:
+
+```markdown
+[reference]: https://mydomain.com/myimage.png
+```
+
+## Example: Image Reference 
+
+This example shows how to include an image (local to the repository) in the
+`README.md` such that it will render in all three places mentioned above.
+
+In the `README.md` a reference image link is placed at the location the image
+should be rendered:
+
+```markdown
+![my example image][blueapi]
+```
+
+at the bottom of the `README.md`, link to a `raw.githubusercontent.com` URL.
+This is placed below a comment:
+
+```markdown
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+[blueapi]: https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png
+```
+
+The absolute URL is used to allow PyPI to render the image. If PyPI is not
+required a relative URL can be used which will work for GitHub rendering.
+
+The `README.md` content is included in the Sphinx build (for example `index.md`)
+but will stop when it reaches the comment:
+
+````markdown
+```{include} ../README.md
+:end-before: <!-- README only content
+```
+````
+
+After this include block the reference can be redefined to point to the local
+image, relative to the root of the Spinx build:
+
+```markdown
+[blueapi]: images/blueapi.png
+```
+
+This ensures that a frozen version of the image at the time the docs are built
+is used for the documentation rather than an image on a branch.
+
+Note that if using a `raw.githubusercontent.com` URL pointing to an image on a
+branch, e.g:
+```
+https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png
+```
+it is possible that the image will be removed or change over time. This would
+affect the content displayed on PyPI, even for releases already made.
+
+To mitigate this it may be desired to point to fixed versions of such assets,
+via a commit hash or a tag URL. For example an image at a specific tag:
+```
+https://raw.githubusercontent.com/DiamondLightSource/blueapi/0.4.0/docs/images/blueapi.png
+```
+or an image at a specific commit:
+```
+https://raw.githubusercontent.com/DiamondLightSource/blueapi/7bbc94e0d61da2a4ce4de6a1285c4cc0e4ba67f2/docs/images/blueapi.png
+```
+This may incur a prohibitive maintenance cost, in constantly updating references
+when releases are made, so use of these fixed images is left as a per-project
+decision.
+
+
+## Example: Logo
+
+A logo may also be added to the `README.md`. 
+
+
+Given that the `README.md` layout has not been drastically changed from the
+template, the following HTML image style code may be placed at the very top of
+`README.md`:
+```html
+<img src="https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi-logo.svg"
+     style="background: none" width="120px" height="120px" align="right">
+```
+
+The width and height may be adjusted to suit the particular project logo.