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

@@ -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'

docs/index.rst

@@ -29,6 +29,14 @@ Data Endpoints
    widgets
    stats
 
+Entities
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   entities
+
 Forms
 -----
 

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,

requirements/docs.in

@@ -1 +1,2 @@
 sphinx
+myst-parser

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