Update Client docs. Simplify docs structure.

Author: fkdosilovic

docs/source/api/clients.rst

@@ -1,6 +1,46 @@
 Clients Module
 ==============
 
-.. automodule:: judge0.clients
-   :members:
-   :member-order: groupwise
+
+.. autoclass:: judge0.clients.Client
+    :exclude-members: API_KEY_ENV
+
+.. autoclass:: judge0.clients.ATD
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.ATDJudge0CE
+    :show-inheritance:
+    :exclude-members: DEFAULT_ENDPOINT, DEFAULT_HOST, HOME_URL, DEFAULT_ABOUT_ENDPOINT,
+                      DEFAULT_CONFIG_INFO_ENDPOINT, DEFAULT_LANGUAGE_ENDPOINT, DEFAULT_LANGUAGES_ENDPOINT,
+                      DEFAULT_STATUSES_ENDPOINT, DEFAULT_CREATE_SUBMISSION_ENDPOINT, DEFAULT_GET_SUBMISSION_ENDPOINT,
+                      DEFAULT_CREATE_SUBMISSIONS_ENDPOINT, DEFAULT_GET_SUBMISSIONS_ENDPOINT, get_about,
+                      get_config_info, get_language, get_languages, get_statuses, create_submission, get_submission,
+                      create_submissions, get_submissions
+
+.. autoclass:: judge0.clients.ATDJudge0ExtraCE
+    :show-inheritance:
+    :exclude-members: DEFAULT_ENDPOINT, DEFAULT_HOST, HOME_URL, DEFAULT_ABOUT_ENDPOINT,
+                      DEFAULT_CONFIG_INFO_ENDPOINT, DEFAULT_LANGUAGE_ENDPOINT, DEFAULT_LANGUAGES_ENDPOINT,
+                      DEFAULT_STATUSES_ENDPOINT, DEFAULT_CREATE_SUBMISSION_ENDPOINT, DEFAULT_GET_SUBMISSION_ENDPOINT,
+                      DEFAULT_CREATE_SUBMISSIONS_ENDPOINT, DEFAULT_GET_SUBMISSIONS_ENDPOINT, get_about,
+                      get_config_info, get_language, get_languages, get_statuses, create_submission, get_submission,
+                      create_submissions, get_submissions
+
+
+.. autoclass:: judge0.clients.Rapid
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.RapidJudge0CE
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.RapidJudge0ExtraCE
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.Sulu
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.SuluJudge0CE
+    :show-inheritance:
+
+.. autoclass:: judge0.clients.SuluJudge0ExtraCE
+    :show-inheritance:

docs/source/api/index.rst

@@ -3,4 +3,4 @@ Types Module
 
 .. automodule:: judge0.base_types
    :members:
-   :undoc-members:
+

docs/source/api/types.rst

@@ -21,7 +21,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
-    "sphinx.ext.autosummary",
+    # "sphinx.ext.autosummary",
     "sphinx_autodoc_typehints",
     "sphinx_multiversion",
 ]
@@ -47,7 +47,7 @@
 
 autodoc_default_options = {
     "members": True,
-    "undoc-members": True,
+    "undoc-members": False,
     "private-members": False,
     "special-members": False,
     "inherited-members": False,

docs/source/conf.py

@@ -25,15 +25,14 @@ You can run minimal Hello World example in three easy steps:
 3. Run the script.
 
 Want to learn more
-------------------
-
+==================
 
 To learn what is happening behind the scenes and how to best use Judge0 Python
 SDK to facilitate the development of your own product see In Depth guide and
 Examples.
 
 Getting Involved
-----------------
+================
 
 TODO
 
@@ -43,12 +42,16 @@ TODO
       :titlesonly:
       :hidden:
 
-      api/index
+      api/api
+      api/submission
+      api/clients
+      api/types
 
 .. toctree::
       :caption: Getting Involved
       :glob:
       :titlesonly:
       :hidden:
 
-      contributors_guide/index
+      contributors_guide/contributing
+      contributors_guide/release_notes

docs/source/contributors_guide/index.rst

@@ -10,6 +10,24 @@
 
 
 class Client:
+    """Base class for all clients.
+
+    Parameters
+    ----------
+    endpoint : str
+        Client's default endpoint.
+    auth_headers : dict
+        Request authentication headers.
+
+    Attributes
+    ----------
+    API_KEY_ENV : str
+        Environment variable where judge0-python should look for API key for
+        the client. Set to default values for ATD, RapidAPI, and Sulu clients.
+    """
+
+    # Environment variable where judge0-python should look for API key for
+    # the client. Set to default values for ATD, RapidAPI, and Sulu clients.
     API_KEY_ENV: ClassVar[str] = None
 
     def __init__(
@@ -24,7 +42,6 @@ def __init__(
         self.retry_strategy = retry_strategy
         self.session = requests.Session()
 
-        # TODO: Should be handled differently.
         try:
             self.languages = self.get_languages()
             self.config = self.get_config_info()
@@ -39,6 +56,13 @@ def __del__(self):
 
     @handle_too_many_requests_error_for_preview_client
     def get_about(self) -> dict:
+        """Get general information about judge0.
+
+        Returns
+        -------
+        dict
+            General information about judge0.
+        """
         response = self.session.get(
             f"{self.endpoint}/about",
             headers=self.auth_headers,
@@ -48,6 +72,13 @@ def get_about(self) -> dict:
 
     @handle_too_many_requests_error_for_preview_client
     def get_config_info(self) -> Config:
+        """Get information about client's configuration.
+
+        Returns
+        -------
+        Config
+            Client's configuration.
+        """
         response = self.session.get(
             f"{self.endpoint}/config_info",
             headers=self.auth_headers,
@@ -57,20 +88,46 @@ def get_config_info(self) -> Config:
 
     @handle_too_many_requests_error_for_preview_client
     def get_language(self, language_id: int) -> Language:
+        """Get language corresponding to the id.
+
+        Parameters
+        ----------
+        language_id : int
+            Language id.
+
+        Returns
+        -------
+        Language
+            Language corresponding to the passed id.
+        """
         request_url = f"{self.endpoint}/languages/{language_id}"
         response = self.session.get(request_url, headers=self.auth_headers)
         response.raise_for_status()
         return Language(**response.json())
 
     @handle_too_many_requests_error_for_preview_client
     def get_languages(self) -> list[Language]:
+        """Get a list of supported languages.
+
+        Returns
+        -------
+        list of language
+            A list of supported languages.
+        """
         request_url = f"{self.endpoint}/languages"
         response = self.session.get(request_url, headers=self.auth_headers)
         response.raise_for_status()
         return [Language(**lang_dict) for lang_dict in response.json()]
 
     @handle_too_many_requests_error_for_preview_client
     def get_statuses(self) -> list[dict]:
+        """Get a list of possible submission statuses.
+
+        Returns
+        -------
+        list of dict
+            A list of possible submission statues.
+        """
         response = self.session.get(
             f"{self.endpoint}/statuses",
             headers=self.auth_headers,
@@ -80,20 +137,43 @@ def get_statuses(self) -> list[dict]:
 
     @property
     def version(self):
+        """Property corresponding to the current client's version."""
         if not hasattr(self, "_version"):
             _version = self.get_about()["version"]
             setattr(self, "_version", _version)
         return self._version
 
     def get_language_id(self, language: Union[LanguageAlias, int]) -> int:
-        """Get language id corresponding to the language alias for the client."""
+        """Get language id corresponding to the language alias for the client.
+
+        Parameters
+        ----------
+        language : LanguageAlias or int
+            Language alias or language id.
+
+        Returns
+        -------
+            Language id corresponding to the language alias.
+        """
         if isinstance(language, LanguageAlias):
             supported_language_ids = LANGUAGE_TO_LANGUAGE_ID[self.version]
             language = supported_language_ids.get(language, -1)
         return language
 
     def is_language_supported(self, language: Union[LanguageAlias, int]) -> bool:
-        """Check if language is supported by the client."""
+        """Check if language is supported by the client.
+
+        Parameters
+        ----------
+        language : LanguageAlias or int
+            Language alias or language id.
+
+        Returns
+        -------
+        bool
+            Return True if language is supported by the client, otherwise returns
+            False.
+        """
         language_id = self.get_language_id(language)
         return any(language_id == lang.id for lang in self.languages)
 
@@ -208,9 +288,6 @@ def create_submissions(self, submissions: Submissions) -> Submissions:
                     f"{submission.language}!"
                 )
 
-        # TODO: Maybe raise an exception if the number of submissions is bigger
-        # than the batch size a client supports?
-
         submissions_body = [submission.as_body(self) for submission in submissions]
 
         response = self.session.post(
@@ -516,7 +593,15 @@ def __init__(self, api_key, **kwargs):
 
 
 class Sulu(Client):
-    """Base class for all Sulu clients."""
+    """Base class for all Sulu clients.
+
+    Parameters
+    ----------
+    endpoint : str
+        Default request endpoint.
+    api_key : str, optional
+        Sulu API key.
+    """
 
     API_KEY_ENV: ClassVar[str] = "JUDGE0_SULU_API_KEY"
 
@@ -530,7 +615,13 @@ def __init__(self, endpoint, api_key=None, **kwargs):
 
 
 class SuluJudge0CE(Sulu):
-    """Sulu client for CE flavor."""
+    """Sulu client for CE flavor.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Sulu API key.
+    """
 
     DEFAULT_ENDPOINT: ClassVar[str] = "https://judge0-ce.p.sulu.sh"
     HOME_URL: ClassVar[str] = "https://sparkhub.sulu.sh/apis/judge0/judge0-ce/readme"
@@ -544,7 +635,13 @@ def __init__(self, api_key=None, **kwargs):
 
 
 class SuluJudge0ExtraCE(Sulu):
-    """Sulu client for Extra CE flavor."""
+    """Sulu client for Extra CE flavor.
+
+    Parameters
+    ----------
+    api_key : str
+        Sulu API key.
+    """
 
     DEFAULT_ENDPOINT: ClassVar[str] = "https://judge0-extra-ce.p.sulu.sh"
     HOME_URL: ClassVar[str] = (