From b8eb6d0e2e83e114655cffc68b2c37495b7d755a Mon Sep 17 00:00:00 2001
From: "Jonas K."
 <33803767+EverythingElseWasAlreadyTaken@users.noreply.github.com>
Date: Tue, 17 Dec 2024 00:11:34 +0100
Subject: [PATCH] docs: Add readme.md for docs and add imgconverter to sphinx
 extensions. (#257)

Add a readme for the docs with build instructions for the documentation.

Add sphinx.ext.imgconverter to conf.py, which is needed to convert svg files for the latexpdf output.
The extension uses ImageMagick to perform conversions and will not work if ImageMagick is not installed.

Signed-off-by: Jonas K. <j0nask@proton.me>
---
 docs/readme.md      | 88 +++++++++++++++++++++++++++++++++++++++++++++
 docs/source/conf.py |  1 +
 2 files changed, 89 insertions(+)
 create mode 100644 docs/readme.md

diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 00000000..1240166f
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,88 @@
+# FABulous docs
+
+The upstream FABulous documentation is available at [https://fabulous.readthedocs.io](https://fabulous.readthedocs.io/en/latest/)
+
+
+## General
+Our docs are built using [Sphinx](https://www.sphinx-doc.org/en/master).
+The documentation is written in [reStructuredText](https://docutils.sourceforge.io/rst.html) format.
+
+
+## Prerequisites
+To build the documentation, you should already have set up your virtual environment and installed the required packages to use FABulous
+as described in the [README](../README.md). Make sure you have picked the right FABulous branch, you want to build the documentation for.
+
+First source your virtual environment:
+```bash
+$ source venv/bin/activate
+```
+
+Then navigate to the `docs` directory and install the required pacakges:
+```bash
+(venv) $ cd docs
+(vevn) $ pip install -r requirements.txt
+```
+
+
+## Building the documentation
+
+### HTML format
+
+To build the documentation in HTML format, run:
+
+```bash
+(venv) $ make html
+```
+This should create a `build/html/` directory path in the `docs` directory for the HTML documentation.
+
+Open it with your browser:
+
+```bash
+(venv) $ xdg-open build/html/index.html
+```
+
+### PDF format
+
+If you want to build the documentation in PDF format, you need to install additional packages.
+and a working LaTeX installation on your system, you can find the needed packages in the
+[LaTeXBuilder sphinx documentation](https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder).
+You also need to install [Imagemagic](https://imagemagick.org/script/index.php), which you can install via `apt-get`:
+
+```bash
+$ sudo apt-get install imagemagick
+```
+
+To build the documentation in PDF format, run:
+
+```bash
+(venv) $ make latexpdf
+```
+
+This should create a `build/latex/` directory path in the `docs` directory for the PDF documentation.
+The PDF file is named `fabulous.pdf`.
+
+Open it with your PDF viewer:
+
+```bash
+(venv) $ xdg-open build/latex/fabulous.pdf
+```
+
+### Clean the build directory
+
+To clean the build directory, run:
+
+```bash
+(venv) $ make clean
+```
+
+This will remove the `build/` directory.
+
+## Contributing
+
+Thank you for considering contributing to FABulous!
+If you find any issues or have any suggestions, improvements, new features or questions,
+please open an [issue](https://github.com/FPGA-Research-Manchester/FABulous/issues),
+start a [discussion](https://github.com/FPGA-Research-Manchester/FABulous/discussions)
+or create a [pull request](https://github.com/FPGA-Research-Manchester/FABulous/pulls).
+
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 998c8bbc..d0d5b426 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -24,6 +24,7 @@
     "sphinx.ext.napoleon",
     "sphinx-prompt",
     "sphinx_copybutton",
+    "sphinx.ext.imgconverter",
 ]
 
 intersphinx_mapping = {