Add mocked imports for requests and pydantic to avoid installation in docs env. Remove tables from docstrings.

fkdosilovic · fkdosilovic · commit dbfd71605a3e · 2024-12-14T18:14:57.000+01:00
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1,2 @@
-sphinx-rtd-theme==3.0.2
+sphinx-rtd-theme==3.0.2
+sphinx-autodoc-typehints==2.3.0
diff --git a/docs/source/api_index.rst b/docs/source/api_index.rst
@@ -16,4 +16,11 @@ Submission Module
 
 .. automodule:: judge0.submission
    :members:
-   :undoc-members:
+   :member-order: groupwise
+
+Clients Module
+-----------------
+
+.. automodule:: judge0.clients
+   :members:
+   :member-order: groupwise
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,6 +22,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
+    "sphinx_autodoc_typehints",
 ]
 
 templates_path = ["_templates"]
@@ -52,5 +53,6 @@
     "special-members": False,
     "inherited-members": False,
 }
+autodoc_mock_imports = ["requests", "pydantic"]
 
 napoleon_google_docstring = False
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,6 +1,10 @@
 Judge0 Python SDK documentation
 ===============================
 
+.. note::
+
+   This project is under active development.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents
diff --git a/src/judge0/api.py b/src/judge0/api.py
@@ -188,19 +188,25 @@ def wait(
 def create_submissions_from_test_cases(
     submissions: Union[Submission, Submissions],
     test_cases: Optional[Union[TestCaseType, TestCases]] = None,
-):
+) -> Union[Submission, list[Submission]]:
     """Create submissions from the (submission, test_case) pairs.
 
-    The following table contains the return type based on the types of
-    `submissions` and `test_cases` arguments:
+    This function always returns a deep copy so make sure you are using the
+    returned submission(s).
 
-    | submissions | test_cases | returns     |
-    |:------------|:-----------|:------------|
-    | Submission  | TestCase   | Submission  |
-    | Submission  | TestCases  | Submissions |
-    | Submissions | TestCase   | Submissions |
-    | Submissions | TestCases  | Submissions |
+    Parameters
+    ----------
+    submissions : Submission or Submissions
+        Base submission(s) that need to be expanded with test cases.
+    test_cases: TestCaseType or TestCases
+        Test cases.
 
+    Returns
+    -------
+    Submissions or Submissions
+        A single submission if submissions arguments is of type Submission or
+        source_code argument is provided, and test_cases argument is of type
+        TestCase. Otherwise returns a list of submissions.
     """
     if isinstance(submissions, Submission):
         submissions_list = [submissions]
@@ -275,16 +281,6 @@ def async_execute(
 
     Aliases: `async_run`.
 
-    The following table contains the return type based on the types of
-    `submissions` (or `source_code`) and `test_cases` arguments:
-
-    | submissions | test_cases | returns     |
-    |:------------|:-----------|:------------|
-    | Submission  | TestCase   | Submission  |
-    | Submission  | TestCases  | Submissions |
-    | Submissions | TestCase   | Submissions |
-    | Submissions | TestCases  | Submissions |
-
     Parameters
     ----------
     client : Client or Flavor, optional
@@ -300,7 +296,9 @@ def async_execute(
     Returns
     -------
     Submission or Submissions
-        A single submission or a list of submissions.
+        A single submission if submissions arguments is of type Submission or
+        source_code argument is provided, and test_cases argument is of type
+        TestCase. Otherwise returns a list of submissions.
 
     Raises
     ------
@@ -331,16 +329,6 @@ def sync_execute(
 
     Aliases: `execute`, `run`, `sync_run`.
 
-    The following table contains the return type based on the types of
-    `submissions` (or `source_code`) and `test_cases` arguments:
-
-    | submissions | test_cases | returns     |
-    |:------------|:-----------|:------------|
-    | Submission  | TestCase   | Submission  |
-    | Submission  | TestCases  | Submissions |
-    | Submissions | TestCase   | Submissions |
-    | Submissions | TestCases  | Submissions |
-
     Parameters
     ----------
     client : Client or Flavor, optional
@@ -356,7 +344,9 @@ def sync_execute(
     Returns
     -------
     Submission or Submissions
-        A single submission or a list of submissions.
+        A single submission if submissions arguments is of type Submission or
+        source_code argument is provided, and test_cases argument is of type
+        TestCase. Otherwise returns a list of submissions.
 
     Raises
     ------

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		`-sphinx-rtd-theme==3.0.2`
	`1`	`+sphinx-rtd-theme==3.0.2`
	`2`	`+sphinx-autodoc-typehints==2.3.0`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,7 @@`
`22`	`22`	`"sphinx.ext.autodoc",`
`23`	`23`	`"sphinx.ext.napoleon",`
`24`	`24`	`"sphinx.ext.autosummary",`
	`25`	`+ "sphinx_autodoc_typehints",`
`25`	`26`	`]`
`26`	`27`
`27`	`28`	`templates_path = ["_templates"]`
`@@ -52,5 +53,6 @@`
`52`	`53`	`"special-members": False,`
`53`	`54`	`"inherited-members": False,`
`54`	`55`	`}`
	`56`	`+autodoc_mock_imports = ["requests", "pydantic"]`
`55`	`57`
`56`	`58`	`napoleon_google_docstring = False`