From 2b557f429b0ec2cfe88ba1e5f7d667d8bdcf4073 Mon Sep 17 00:00:00 2001
From: Marcel Koch <marcel.koch@kit.edu>
Date: Thu, 12 Sep 2024 16:11:46 +0200
Subject: [PATCH] [doc] add documentation on the documentation setup

---
 doc/developer-guide/documentation.md | 31 ++++++++++++++++++++++++++++
 doc/index.md                         |  8 +++++++
 2 files changed, 39 insertions(+)
 create mode 100644 doc/developer-guide/documentation.md

diff --git a/doc/developer-guide/documentation.md b/doc/developer-guide/documentation.md
new file mode 100644
index 00000000000..af53b91f191
--- /dev/null
+++ b/doc/developer-guide/documentation.md
@@ -0,0 +1,31 @@
+# Documentation Setup
+
+The documentation for Ginkgo is set up using
+
+- [Sphinx](https://www.sphinx-doc.org/)
+- [Doxygen](https://www.doxygen.nl/)
+
+Doxygen is used *only* for documenting the API through comments in the source code.
+No explicit Doxygen file (i.e. a file with only Doxygen content) shall be written.
+The `@cmd` syntax is used, where `cmd` is any valid doxygen command, see the list [here](https://www.doxygen.nl/manual/commands.html) for reference.
+
+Any other documentation is done via Sphinx.
+This includes the tutorial, how-to, and explanation aspects of the [diataxis](https://diataxis.fr/) approach.
+The [MyST](https://myst-parser.readthedocs.io) extension is used to allow markdown files as Sphinx input.
+Only markdown files shall be written for the Sphinx documentation.
+Admonitions shall be added with the `:::` syntax. 
+The triple \` is reserved for code blocks.
+
+A connection from Sphinx to doxygen is established via [doxylink](https://github.com/sphinx-contrib/doxylink).
+With this, it is possible to reference the doxygen documentation by using the syntax 
+```md
+{doxy}`gko::matrix::Dense`
+```
+In the other direction, only the main page for the Sphinx documentation is available through doxygen.
+It is directly added to the `DoxygenLayout.xml` as a relative link.
+
+The connections between Sphinx and doxygen rely on correctly set output directories for both.
+The Sphinx output dir is the main one, and the doxygen output dir is defined relative to that.
+The Sphinx output dir is set to `SPHINX_OUTPUT_DIR=$CMAKE_BINARY_DIR/doc/html` and the doxygen output *has* to be put under `SPHINX_OUTPUT_DIR/_doxygen`.
+There will be an automatically generated subdir `html` of `_doxygen`.
+As the documentation setup uses relative path between doxygen and sphinx, messing up the path will lead to broken references.
\ No newline at end of file
diff --git a/doc/index.md b/doc/index.md
index 0dd647b6c22..9c40571e5c6 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -28,4 +28,12 @@ Publications <publications>
 contributing
 Using Ginkgo <using-ginkgo>
 API <_doxygen/html/index.html#https://>
+:::
+
+:::{toctree}
+:hidden:
+:maxdepth: 2
+:caption: Developer Guide:
+
+developer-guide/documentation
 :::
\ No newline at end of file