Clarify Python library usage and document current ScanCode limitations

docs/scancode_api_example.py

@@ -0,0 +1,9 @@
+import scancode
+import scancode.api
+
+print("ScanCode modules imported successfully")
+
+
+# ScanCode does not currently expose a stable public Python API
+# This example demonstrates importability only
+

docs/source/how-to-guides/library_usage.rst

@@ -0,0 +1,66 @@
+Using ScanCode from Python
+=========================
+
+ScanCode Toolkit is primarily designed to be used as a command-line tool.
+At present, it does **not** expose a stable, documented public Python API
+for invoking scans programmatically.
+
+However, ScanCode can still be integrated into Python-based workflows by
+invoking its command-line interface from Python code. ScanCode modules
+can also be imported, though execution-related APIs are considered internal
+and subject to change.
+
+Installation
+------------
+
+ScanCode Toolkit must be installed with all optional dependencies:
+
+.. code-block:: bash
+
+    pip install scancode-toolkit[full]
+
+
+Using ScanCode via subprocess
+-----------------------------
+
+The recommended way to execute a ScanCode scan from Python is by invoking
+the ScanCode command-line interface using the ``subprocess`` module.
+
+.. code-block:: python
+
+    import subprocess
+
+    subprocess.run(
+        [
+            "scancode",
+            "--license",
+            "--json-pp",
+            "results.json",
+            "/path/to/scan",
+        ],
+        check=True,
+    )
+
+
+Importing ScanCode modules
+--------------------------
+
+ScanCode modules can be imported in Python. This can be useful for accessing
+internal utilities or for exploratory purposes, but these APIs are not
+considered stable for running scans.
+
+.. code-block:: python
+
+    import scancode
+    import scancode.api
+
+
+Notes
+-----
+
+- ScanCode does not currently provide a public Python function to run scans
+  directly.
+- Internal APIs may change without notice and should not be relied upon for
+  production integrations.
+- For full scan configuration options, refer to the ScanCode command-line
+  documentation.

tests/packagedcode/test_library_usage_example.py

@@ -0,0 +1,2 @@
+def test_import_and_basic_scan():
+   import scancode.api