fix serverless docs, pin statsmodels (#331)

Co-authored-by: viseshrp <[email protected]>

Author: viseshrp

doc/source/serverless/caveats.rst

@@ -87,20 +87,19 @@ Example: Threading with Serverless ADR
         for t in threads:
             t.join()
 
-Common Pitfalls and Solutions
------------------------------
-
-- **Error: "ADR has not been set up" in worker processes**
-
-  _Cause_: ``ADR.setup()`` was not called in the worker process.
-
-  _Solution_: Call ``adr.setup()`` early in each new process, as shown above.
-
-- **Race conditions or inconsistent state due to multiple ``setup()`` calls**
-
-  _Cause_: Concurrent calls to ``setup()`` from multiple threads.
+Serverless ADR Usage Within Django Apps
+--------------------------------------
 
-  _Solution_: Call ``setup()`` only once in the main thread before spawning workers.
+- Serverless ADR internally configures Django settings and environment variables at the
+  process level during ``ADR.setup()``.
+- Because Django settings are designed to be configured once per process, **attempting
+  to initialize Serverless ADR inside an existing Django application causes conflicts.**
+- Specifically, setting up Serverless ADR tries to configure Django a second time, which
+  is unsupported and results in errors or unpredictable behavior.
+- This means **embedding or using Serverless ADR as a Django app within another Django
+  project is not currently supported and strongly discouraged.**
+- If you require integration, consider separating Serverless ADR usage into a dedicated
+  process or microservice to avoid Django settings conflicts.
 
 Summary and Best Practices
 --------------------------
@@ -109,7 +108,8 @@ Summary and Best Practices
 - In multiprocessing scenarios, call ``setup()`` separately in each spawned process.
 - Avoid calling ``setup()`` multiple times or concurrently within the same process.
 - Share the ADR instance across threads within a process after setup completes.
+- Avoid embedding Serverless ADR within other Django apps due to Django configuration conflicts.
 - If unsure whether setup is needed, check ``adr.is_setup`` before calling.
 
 By following these guidelines, you ensure stable and consistent Serverless ADR usage
-in complex multi-threaded or multi-process environments.
+in complex multi-threaded or multi-process environments without risking Django conflicts.

doc/source/serverless/configuration.rst

@@ -63,9 +63,15 @@ The primary configuration options for the ``ADR`` class constructor are:
 Environment Variables
 =====================
 
-Serverless ADR supports several environment variables to configure its runtime behavior,
-database connections, security settings, and media/static file handling. These variables
-can be used for legacy configurations or advanced deployments.
+.. warning::
+
+   **Use of environment variables for Serverless ADR configuration is strongly discouraged.**
+   Environment variables represent a legacy configuration method and can lead to hidden,
+   hard-to-debug issues, security risks (such as leaking secrets), and inconsistent behavior
+   especially in multi-instance or containerized deployments.
+
+   It is highly recommended to use explicit constructor parameters and configuration files
+   for all setup and runtime options instead.
 
 Core Variables
 --------------
@@ -86,17 +92,11 @@ Core Variables
   URL prefix used to access media files remotely. Must start and end with a slash, e.g., ``/media/``.
   Corresponds to the ``media_url`` constructor parameter.
 
-- **CEI_NEXUS_LOCAL_ALLOW_REMOTE_ACCESS**
-  If set to any value, allows remote access to a local database server (use cautiously).
-
-- **CEI_NEXUS_SERVE_STATIC_FILES**
-  If ``True``, enables Django’s built-in static and media file serving (not recommended for production).
-
 Database Connection Variables
 -----------------------------
 
 - **CEI_NEXUS_DB_ENGINE**
-  Database engine string (e.g., ``django.db.backends.postgresql_psycopg2``). Defaults to PostgreSQL.
+  Database engine. Defaults to SQLite.
 
 - **CEI_NEXUS_DB_DATABASE_NAME**
   Name of the database to connect to. Defaults to ``nexus_database``.
@@ -108,78 +108,29 @@ Database Connection Variables
   Password for the database user. Default is ``cei``.
 
 - **CEI_NEXUS_DB_HOSTNAME**
-  Database server hostname or IP address. Defaults to ``127.0.0.1``.
+  Database server hostname or IP address. Defaults to the path to the SQLite database file.
 
 - **CEI_NEXUS_DB_PORT**
-  Database server port number. Default is ``5432``.
+  Database server port number. Default is not set for SQLite.
 
-Security and Server Variables
------------------------------
-
-- **CEI_NEXUS_SERVER_NAME**
-  Human-readable name of the server. Defaults to ``mixed``.
+Security Variables
+------------------
 
 - **CEI_NEXUS_SECRET_KEY**
   Django secret key used internally. If not provided, a built-in default key is used (not recommended for production).
 
-- **CEI_NEXUS_ALLOWED_HOSTS**
-  Comma-separated list of allowed hostnames for accessing the server (e.g., ``localhost,127.0.0.1``).
-
-- **CEI_NEXUS_TRUSTED_ORIGINS**
-  List of trusted origins for unsafe requests like POST, supporting wildcards (e.g., ``https://*.example.com``).
-
-- **CEI_NEXUS_HTTPS_SECURED**
-  Boolean flag to indicate if the server runs behind HTTPS only. Enables security headers.
-
-- **CEI_NEXUS_HSTS_SECURED**
-  Enables HTTP Strict Transport Security (HSTS) headers.
-
-- **CEI_NEXUS_HSTS_SECONDS**
-  Duration in seconds for HSTS policy enforcement. Use with caution to avoid locking out clients.
-
-- **CEI_NEXUS_X_FRAME_OPTIONS**
-  Sets the HTTP X-Frame-Options header globally for protection against clickjacking.
-
 Advanced / Optional Variables
 -----------------------------
 
 - **CEI_NEXUS_ENABLE_ACLS**
   Enables per-category Access Control Lists (ACLs). Experimental and not recommended for general use.
 
-- **CEI_NEXUS_ACLS_NGINX_LOCATION**
-  NGINX internal location directive for permission-protected media files. Default is ``/media_secured``.
-
-Remote Session Configuration
-----------------------------
-
-- **CEI_NEXUS_REMOTE_WEBSOCKETURL**
-  URL to the NGINX server proxying to the websocket server.
-
-- **CEI_NEXUS_REMOTE_WS_PORT**
-  Port used by the websocket server for WS protocol communication.
-
-- **CEI_NEXUS_REMOTE_HTML_PORT**
-  Port used by the websocket server for HTTP REST communication.
-
-- **CEI_NEXUS_REMOTE_VNCPASSWORD**
-  Password for VNC server sessions.
-
 Usage Notes
 -----------
 
-- When running a non-debug local server, use the following command to enable static file serving:
-
-  .. code-block:: bash
+- Constructor parameters take precedence over environment variables. If both are set, constructor values will be used.
 
-     python manage.py runserver --insecure 0.0.0.0:8000
-
-- Environment variables override constructor parameters if both are set.
-
-- Always set secure secret keys in production environments to protect sensitive data.
-
-- Configure ``CEI_NEXUS_ALLOWED_HOSTS`` and ``CEI_NEXUS_TRUSTED_ORIGINS`` to restrict server access.
-
-- When enabling HTTPS and HSTS, be cautious with duration settings to avoid client lockout.
+- Always set secure secret keys in production environments to protect sensitive data. If you do not set a key, a default will be used.
 
 Example: Setting environment variables in Linux shell:
 
@@ -189,8 +140,6 @@ Example: Setting environment variables in Linux shell:
    export CEI_NEXUS_LOCAL_MEDIA_DIR="/var/data/adr_media"
    export CEI_NEXUS_MEDIA_URL_PREFIX="/media/"
    export CEI_NEXUS_SECRET_KEY="a-very-secure-secret-key"
-   export CEI_NEXUS_ALLOWED_HOSTS="localhost,127.0.0.1"
-   export CEI_NEXUS_HTTPS_SECURED="True"
 
 Example: Passing variables via ``opts`` parameter:
 
@@ -206,14 +155,6 @@ Example: Passing variables via ``opts`` parameter:
    adr = ADR(ansys_installation="/opt/ansys", opts=opts)
    adr.setup()
 
-Summary
--------
-
-Proper use of environment variables allows flexible deployment and integration of Serverless ADR
-into diverse environments, including containerized, cloud, or on-premises infrastructures.
-
-See also the :doc:`configuration` and :doc:`setup` guides for comprehensive initialization instructions.
-
 **Note: Prefer constructor parameters for new projects. Environment variables remain supported primarily for legacy compatibility.**
 
 Best Practices
@@ -252,50 +193,6 @@ Examples
     )
     adr.setup(collect_static=True)
 
-**Multi-database PostgreSQL and SQLite setup:**
-
-.. code-block:: python
-
-    database_config = {
-        "default": {
-            "ENGINE": "postgresql",
-            "NAME": "adr_db",
-            "USER": "adr_user",
-            "PASSWORD": "password",
-            "HOST": "localhost",
-            "PORT": "5432",
-        },
-        "sqlite_local": {
-            "ENGINE": "sqlite3",
-            "NAME": r"C:\Reports\DB\local.sqlite3",
-        },
-    }
-
-    adr = ADR(
-        ansys_installation=r"/opt/ansys",
-        databases=database_config,
-        media_directory=r"/opt/reports/media",
-        static_directory=r"/opt/reports/static",
-        media_url="/media/",
-        static_url="/static/",
-    )
-    adr.setup()
-
-**Docker-based Ansys installation:**
-
-.. code-block:: python
-
-    adr = ADR(
-        ansys_installation="docker",
-        docker_image="ghcr.io/ansys-internal/nexus_dev",
-        db_directory=r"C:\Reports\DB",
-        media_directory=r"C:\Reports\Media",
-        static_directory=r"C:\Reports\Static",
-        media_url="/media/",
-        static_url="/static/",
-    )
-    adr.setup()
-
 Troubleshooting
 ---------------
 
@@ -312,11 +209,5 @@ Troubleshooting
 Summary
 -------
 
-Proper configuration of Serverless ADR ensures seamless database connections, media management, and web serving of report assets. Follow best practices for setup and environment initialization to avoid common issues.
-
-Next Steps
-----------
-
-See the :doc:`setup` guide for detailed startup and initialization instructions.
-
-See the :doc:`media_and_static` guide for managing static and media files in your reports.
+Proper configuration of Serverless ADR ensures seamless database connections, media management, and web serving of report assets.
+Follow best practices for setup and environment initialization to avoid common issues.

doc/source/serverless/copying_objects.rst

@@ -134,7 +134,7 @@ Best Practices
 --------------
 
 - Ensure the target database is properly configured and accessible before copying.
-- Copy related sessions and datasets automatically by copying items or templates.
+- Copy related sessions and datasets automatically by copying items.
 - Always use ``test=True`` initially to preview the number of objects to be copied.
 - Ensure media directories have sufficient space and permissions.
 - Use descriptive ADR query strings to limit copy scope.

doc/source/serverless/embedding_reports.rst

@@ -21,7 +21,7 @@ Generating Embed-Ready HTML
 ---------------------------
 
 Use the ``render_report()`` method of the ADR instance to render a complete
-report or a subset of it as HTML.
+report.
 
 .. code-block:: python
 
@@ -42,8 +42,6 @@ You can also render individual report items using their ``render()`` method:
 .. code-block:: python
 
     item = adr.create_item(String, name="summary_text", content="Summary content here.")
-    item.save()
-
     html_snippet = item.render(context={"plotly": 0})
 
 Embedding Partial Templates or Sections
@@ -63,7 +61,7 @@ Integration Tips
 
 - Make sure your embedded HTML includes references to static and media URLs
   configured during ADR setup so that assets like images and stylesheets
-  load correctly.
+  load correctly and your web server is configured to serve them.
 
 - Use the ``context`` parameter to pass additional context variables
   needed for rendering.
@@ -81,15 +79,14 @@ Example with Flask:
 
 .. code-block:: python
 
+    from ansys.dynamicreporting.core.serverless import ADR
     from flask import Flask, render_template_string
 
     app = Flask(__name__)
 
 
     @app.route("/embedded-report")
     def embedded_report():
-        from ansys.dynamicreporting.core.serverless import ADR
-
         adr = ADR.get_instance()
         my_app_html = "<!-- Your app's HTML here -->"
         html = adr.render_report(name="My Simulation Report")
@@ -112,7 +109,7 @@ Security Considerations
 
 - Validate and sanitize any dynamic input used in filters or templates
   to avoid injection attacks.
-- Limit exposure of internal data by controlling which templates or items
+- Limit exposure of data by controlling which templates or items
   are accessible for embedding.
 
 Summary

doc/source/serverless/examples.rst

@@ -0,0 +1,3 @@
+Examples
+========
+

doc/source/serverless/index.rst

@@ -19,15 +19,14 @@ want to:
 
 - Create, manage, and render reports locally using Python
 - Avoid setting up a centralized ADR service or HTTP connection
-- Maintain full fidelity with the ADR schema (items, templates, layout logic)
-- Output HTML content and media assets for web apps, automation, or
-  documentation pipelines
+- Maintain full fidelity with the ADR schema (items, templates, etc.)
+- Output HTML content and media assets for web and desktop apps.
 
 Serverless ADR is ideal for:
 
 - Local, file-based workflows (e.g., building offline reports)
+- Embedding reports in web or desktop applications
 - Use in batch scripts, Python notebooks, or simulations
-- Building and verifying templates before pushing to production ADR services
 
 Key features
 ============

doc/source/serverless/items.rst

@@ -41,7 +41,6 @@ Items automatically link to the current default session and dataset unless speci
         content="This simulation demonstrates fluid flow around a wing.",
         tags="section=summary project=wing_sim",
     )
-    string_item.save()
 
     # Create a table item with data
     data = np.array(
@@ -71,7 +70,10 @@ Item Properties and Metadata
 
 Items support several useful properties and metadata fields:
 
+- **guid**: Unique identifier for the item, automatically generated.
 - **name**: Unique identifier for the item within the dataset.
+- **type**: The item type (e.g., `string`, `table`, etc.).
+- **date**: Timestamp indicating when the item was created.
 - **content**: The primary payload of the item, type-dependent.
 - **tags**: A space-separated string of key or key=value tags for querying and filtering.
 - **source**: String to track the data origin or generating process.
@@ -94,7 +96,6 @@ Example: Creating and saving an image item
         content="path/to/wing_profile.png",
         tags="section=images project=wing_sim",
     )
-    image_item.save()
 
 After saving, the file is copied into the configured media directory. You can access the uploaded file's storage path using the `file_path` property:
 
@@ -106,7 +107,8 @@ After saving, the file is copied into the configured media directory. You can ac
 This path points to the location within the media directory configured during ADR setup.
 You can use this path for verification, further processing, or serving the media file in your application.
 
-When rendering reports or templates that include media items, the HTML references media files using relative URLs, typically prefixed by the configured media URL (default is `/media/`):
+When rendering reports or templates that include media items, the HTML references media files using relative URLs,
+typically prefixed by the configured media URL (default is `/media/`):
 
 .. code-block:: html
 
@@ -118,7 +120,10 @@ Ensure your web server is configured to serve these media URLs from the media di
 Summary:
 - Set the `content` of file-based items to the local file path before saving.
 - After saving, `file_path` gives the full path to the uploaded media file.
+- When the item is loaded again from the database, `content` will be the relative path to the media file.
 - Rendered reports use relative media URLs; configure your web server accordingly.
+- Use the `media_url` property to get the URL prefix for serving media files.
+- The media URL is typically `/media/` by default.
 
 Rendering Items
 ---------------