Improve documentation (#272)

--------- Co-authored-by: Thomas Ubensee <[email protected]>
exasol · Nov 11, 2024 · 809d776 · 809d776
1 parent c841c24
commit 809d776
Show file tree

Hide file tree

Showing 20 changed files with 28 additions and 1,216 deletions.
diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
@@ -16,6 +16,8 @@
 ## 📚 Documentation
 
 * Added Documentation on Metrics
+* Added additional details regarding adjusted sphinx-multiversion 
+* Restructured documentation
 
 ## 🔩 Internal
 

diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst
@@ -10,4 +10,4 @@
     ../design
     development
     plugins
-    ideas
+    modules/modules
diff --git a/doc/developer_guide/ideas.rst b/doc/developer_guide/ideas.rst
diff --git a/doc/user_guide/modules/modules.rst → doc/developer_guide/modules/modules.rst b/doc/user_guide/modules/modules.rst → doc/developer_guide/modules/modules.rst
@@ -4,7 +4,7 @@ Modules
 .. toctree::
     :maxdepth: 2
 
+    sphinx/sphinx
     nox
     pre_commit_hooks
-    sphinx/sphinx
 
diff --git a/doc/user_guide/modules/nox.rst → doc/developer_guide/modules/nox.rst b/doc/user_guide/modules/nox.rst → doc/developer_guide/modules/nox.rst
diff --git a/doc/user_guide/modules/pre_commit_hooks.rst → ...eloper_guide/modules/pre_commit_hooks.rst b/doc/user_guide/modules/pre_commit_hooks.rst → ...eloper_guide/modules/pre_commit_hooks.rst
diff --git a/doc/developer_guide/modules/sphinx/sphinx.rst b/doc/developer_guide/modules/sphinx/sphinx.rst
@@ -0,0 +1,24 @@
+sphinx
+=======
+
+sphinx-multiversion
++++++++++++++++++++
+
+The `sphinx-multiversion` extension is a modified copy of `Holzhaus/sphinx-multiversion <https://github.com/Holzhaus/sphinx-multiversion>`_. This copy was taken from version :code:`0.24.0`.
+
+It has been adjusted with minor code changes and modified defaults to work seamlessly with Exasol integration projects, which often require a specific project structure and layout. Additionally, it is designed to be used with an HTML theme that supports displaying and selecting multiple versions if the `versions` variable is set in the HTML context of sphinx. As of this writing, the theme used in conjunction with this modified version of `sphinx-multiversion` is `SHIBUYA <https://github.com/lepture/shibuya>`_, version :code:`2024.10.15`.
+
+.. attention::
+
+    **Attribution**
+
+    A big thanks to the original author and project `Jan Holthuis <https://github.com/Holzhaus>`_, as well as `Samuel Dowling <https://github.com/samuel-emrys>`_, as we took various patches for the plugin from his fork.
+
+    Note: Both projects are published under the `BSD-2 license <https://opensource.org/license/bsd-2-clause>`_.
+
+    * https://github.com/sphinx-contrib/multiversion
+    * https://github.com/samuel-emrys/sphinx-multiversion
+
+.. note::
+
+    In the long term, it would be advantageous to remove unnecessary features and code that are not required for Exasol's projects. Adding further tests would also be beneficial. However, the primary goal was to create a low-effort, stable multi-version support solution for our projects.
diff --git a/doc/user_guide/modules/sphinx/multiversion/_templates/versioning.html b/doc/user_guide/modules/sphinx/multiversion/_templates/versioning.html
diff --git a/doc/user_guide/modules/sphinx/multiversion/changelog.rst b/doc/user_guide/modules/sphinx/multiversion/changelog.rst
diff --git a/doc/user_guide/modules/sphinx/multiversion/conf.py b/doc/user_guide/modules/sphinx/multiversion/conf.py