Relative link handling for README inclusion

[joeshannon]

In the docs build the index page includes the top level project README.md. This can cause issues if the README includes images or links to things relative to the top level of the repository.

For example something such as:

![concept](docs/images/blueapi.png)

This causes the Sphinx build to fail as it is resolving things relative to the docs directory. This is probably due to sphinx-doc/sphinx#701.

In the previous rst docs this was worked around by redefining the reference in the docs build i.e.

...possibly from remote locations.

|concept|

The main premise of blueapi is...

..
    Anything below this line is used when viewing README.rst and will be replaced
    when included in index.rst


.. |concept| image:: docs/images/blueapi.png
    :width: 800px

then included in the Sphinx pages with:

.. include:: ../README.rst
    :end-before: when included in index.rst

.. |concept| image:: images/blueapi.png
    :width: 800px

How the documentation is structured...

Workarounds

• Using an eval-rst might work for the Sphinx build but probably not with the GitHub markdown rendering
• An absolute link, as used by PandABlocks-ioc does work but is not ideal for development and is refering to an image on the main branch which could change (or be removed) over time

[joeshannon]

MyST includes a relative-images option (also relative-docs) for file inclusion which looks like it would solve this issue.
This could be added to the template.

[coretl]

This is still possible in MyST, but the syntax is different. E.g. for scanspec in the README we have:

![plot][]

at the bottom of the README we have the link on GitHub:

[plot]: https://raw.githubusercontent.com/dls-controls/scanspec/master/docs/images/plot_spec.png

Then in the docs/index.md it gets overridden:

[plot]: images/plot_spec.png

Does this work for you? If so, please could we have a docs article on Adding images to the README. It could also refer to how we do the logo:

<img src="https://raw.githubusercontent.com/dls-controls/scanspec/main/docs/images/scanspec-logo.svg"
     style="background: none" width="120px" height="120px" align="right">

[coretl]

MyST includes a relative-images option (also relative-docs) for file inclusion which looks like it would solve this issue. This could be added to the template.

Unfortunately whatever you put in the README also has to work on PyPI, and I don't think relative images work there. I could be wrong though...

[joeshannon]

Thanks for the comments and examples.

The relative-images is put in the Sphinx index.md not the README.

E.g

```{include} ../README.md
:relative-images:
:end-before: <!-- README only content

So I think the README would still work as expected on GitHub.

However I have just noticed that even with the current RST README in blueapi, the image doesn't appear on PyPI so perhaps using the raw gh content url is the only reasonable working solution.

Is it worth considering to use absolute commit references to ensure that e.g. images included in releases will not change over time or is it not worth the maintenance cost? I imagine it might be a bit of a pain.

E.g:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/7bbc94e0d61da2a4ce4de6a1285c4cc0e4ba67f2/docs/images/blueapi.png

or:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/0.4.0/docs/images/blueapi.png

instead of:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png

[coretl]

Is it worth considering to use absolute commit references to ensure that e.g. images included in releases will not change over time or is it not worth the maintenance cost? I imagine it might be a bit of a pain.

Yeah, it probably makes sense to do that despite the pain...

[joeshannon]

I'll assign this to me as a reminder to add some documentation as suggested.

[joeshannon]

The how-to has been added (#142 ) so I think this can be closed now.