From 7c890347a3b8dc7b6e1b743cddb37c9ced191ffe Mon Sep 17 00:00:00 2001
From: Kelvin Muchiri <kelvinmuchiri63@gmail.com>
Date: Wed, 7 Aug 2024 14:30:15 +0300
Subject: [PATCH] Add Entities documentation to Sphinx table of contents tree 
 (#2659)

* add entities docs to documentation index

* include markdown in Sphinx build

* use myst_parser to handle markdown in Sphinx

* add myst-parser to docs.in requirements

* fix SuspiciousFileOperation error
---
 docs/conf.py                      |  3 ++-
 docs/index.rst                    |  8 ++++++++
 onadata/libs/utils/image_tools.py |  6 +++---
 requirements/docs.in              |  1 +
 requirements/docs.pip             | 28 ++++++++++++++++++++++++----
 5 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 6e543fe64e..e7b5235097 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -41,13 +41,14 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.imgmath",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
diff --git a/docs/index.rst b/docs/index.rst
index 7e31919856..5f321eb1b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -29,6 +29,14 @@ Data Endpoints
    widgets
    stats
 
+Entities
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   entities
+
 Forms
 -----
 
diff --git a/onadata/libs/utils/image_tools.py b/onadata/libs/utils/image_tools.py
index 6074d4b002..abf3728cc6 100644
--- a/onadata/libs/utils/image_tools.py
+++ b/onadata/libs/utils/image_tools.py
@@ -144,7 +144,7 @@ def get_dimensions(size, longest_side):
     return flat(width, height)
 
 
-def _save_thumbnails(image, path, size, suffix, extension):
+def _save_thumbnails(image, filename, size, suffix, extension):
     with NamedTemporaryFile(suffix=f".{extension}") as temp_file:
         default_storage = get_storage_class()()
 
@@ -156,7 +156,7 @@ def _save_thumbnails(image, path, size, suffix, extension):
             pass
 
         image.save(temp_file.name)
-        default_storage.save(get_path(path, suffix), ContentFile(temp_file.read()))
+        default_storage.save(get_path(filename, suffix), ContentFile(temp_file.read()))
         temp_file.close()
 
 
@@ -191,7 +191,7 @@ def resize_local_env(filename, extension):
     for key in settings.THUMB_ORDER:
         _save_thumbnails(
             image,
-            path,
+            filename,
             conf[key]["size"],
             conf[key]["suffix"],
             settings.DEFAULT_IMG_FILE_TYPE if extension == "non" else extension,
diff --git a/requirements/docs.in b/requirements/docs.in
index 6966869c70..00281ca0ab 100644
--- a/requirements/docs.in
+++ b/requirements/docs.in
@@ -1 +1,2 @@
 sphinx
+myst-parser
\ No newline at end of file
diff --git a/requirements/docs.pip b/requirements/docs.pip
index 177339ca73..41a81900b7 100644
--- a/requirements/docs.pip
+++ b/requirements/docs.pip
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.12
+# This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
 #    pip-compile --output-file=requirements/docs.pip --strip-extras requirements/docs.in
@@ -13,25 +13,43 @@ certifi==2024.7.4
 charset-normalizer==3.3.2
     # via requests
 docutils==0.21.2
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 idna==3.7
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.4
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==2.1.5
     # via jinja2
+mdit-py-plugins==0.4.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==4.0.0
+    # via -r requirements/docs.in
 packaging==24.1
     # via sphinx
 pygments==2.18.0
     # via sphinx
+pyyaml==6.0.2
+    # via myst-parser
 requests==2.32.3
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
 sphinx==7.3.7
-    # via -r requirements/docs.in
+    # via
+    #   -r requirements/docs.in
+    #   myst-parser
 sphinxcontrib-applehelp==1.0.8
     # via sphinx
 sphinxcontrib-devhelp==1.0.6
@@ -44,5 +62,7 @@ sphinxcontrib-qthelp==1.0.7
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.10
     # via sphinx
+tomli==2.0.1
+    # via sphinx
 urllib3==2.2.2
     # via requests