✨ link images in README using relative docs parameter

- unfortunately does not work with href links as it seems

Author: enryH

README.md

@@ -1,9 +1,8 @@
-<div align="center">
-  <img width="300px" src="docs/images/vuegen_logo.svg">
-</div>
-
+<!-- <div align="center">
+  <img width="300px" src="images/vuegen_logo.svg">
+</div> -->
+![VueGen Logo](docs/images/vuegen_logo.svg)
 -----------------
-
 <p align="center">
    VueGen is a Python library that automates the creation of scientific reports.
 </p>
@@ -19,19 +18,22 @@ VueGen automates the creation of scientific reports based on a YAML configuratio
 
 An overview of the VueGen workflow is shown in the figure below:
 
-<p align="center">
+<!-- <p align="center">
 <figure>
-  <img width="650px" src="docs/images/vuegen_graph_abstract.png" alt="VueGen overview"/>
+  <img width="650px" src="images/vuegen_graph_abstract.png" alt="VueGen overview"/>
 </figure>
-</p>
+</p> -->
+![VueGen Abstract](docs/images/vuegen_graph_abstract.png)
 
 Also, the class diagram for the project is presented below to illustrate the architecture and relationships between classes:
 
-<p align="center">
+<!-- <p align="center">
 <figure>
-  <img width="650px" src="docs/images/vuegen_classdiagram_noattmeth.png" alt="VueGen class diagram"/>
+  <img width="650px" src="images/vuegen_classdiagram_noattmeth.png" alt="VueGen class diagram"/>
 </figure>
-</p>
+</p> -->
+
+![VueGen Class Diagram](docs/images/vuegen_classdiagram_noattmeth.png)
 
 ## Installation
 

docs/README.md

@@ -30,3 +30,10 @@ sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../vuege
 # build docs
 sphinx-build -n -W --keep-going -b html ./ ./_build/
 ```
+
+## Include repo README.md into docs
+
+Relative links are used in the main README, which need to be resolved when building. It's
+possible to include the a `relative-docs` option if one uses `index.md` ([see docs](https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-a-file-from-outside-the-docs-folder-like-readme-md)). This does not work
+with `href` links, only native markdown links.
+

docs/index.md

@@ -0,0 +1,25 @@
+# Overview
+
+<!-- https://myst-parser.readthedocs.io/en/latest/faq/index.html
+#include-a-file-from-outside-the-docs-folder-like-readme-md -->
+```{include} ../README.md
+:start-line: 0
+:relative-docs: docs
+:relative-images:
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Modules
+:hidden:
+
+reference/vuegen
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: MISC:
+:hidden:
+
+README.md
+```