Documentation update (#181)

* fix for issue #175

* clear most docstrings reference warnings

* update more docstrings

* suppress ref warnings

---------

Co-authored-by: Jon Walker <jonathan.walker@sas.com>

Author: SilvestriStefano

doc/conf.py

@@ -44,23 +44,32 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
-    "numpydoc",  # "sphinx.ext.napoleon",
+    "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
 ]
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
+    "python": ("https://docs.python.org/3/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "swat": ("https://sassoftware.github.io/python-swat/", None),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
     "betamax": ("https://betamax.readthedocs.io/en/latest/", None),
-    "requests": ("https://2.python-requests.org/en/master/", None),
-    "tox": ("https://tox.readthedocs.io/en/latest/", None),
-    "flake8": ("http://flake8.pycqa.org/en/latest/", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+    "tox": ("https://tox.wiki/en/latest/", None),
+    "flake8": ("https://flake8.pycqa.org/en/latest/", None),
 }
 
 autosummary_generate = True
 
+# Napoleon settings
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_ivar = True
+napoleon_use_rtype = False
+
 todo_include_todos = True
 
 todo_emit_warnings = True
@@ -92,6 +101,17 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+# Suppress warnings 'py:class reference target not found: <type>'
+nitpicky = True
+nitpick_ignore = [
+    ('py:class','optional'),
+    ('py:class','json.encoder.JSONEncoder'), # I don't understand why it can't find it
+    ('py:class','Response'),
+    ('py:class','Request'),
+    ('py:class','_io.BytesIO'),
+    ('py:class','sasctl.utils.pymas.ds2.Ds2Variable'), # not sure what is wrong 
+    ('py:class','sasctl._services.service.Service') # should the Service class be documented?
+]
 
 # -- Options for HTML output -------------------------------------------------
 

doc/index.rst

@@ -4,11 +4,6 @@ sasctl
 
 Version |version|
 
-.. toctree::
-    :maxdepth: 3
-    :hidden: true
-
-    index
 
 Introduction
 ------------
@@ -313,7 +308,7 @@ Logging
 +++++++
 
 All logging is handled through the built-in :mod:`logging` module with standard module-level loggers.  The one exception
-to this is :class:`.Session` request/response logging.  Sessions contain a :attr:`~sasctl.core.Session.message_log` which is exclusively used
+to this is :class:`.Session` request/response logging.  Sessions contain a `message_log` which is exclusively used
 to record requests and responses made through the session.  Message recording can be configured on a per-session basis
 by updating this logger, or the ``sasctl.core.session`` logger can be configured to control all message recording by all sessions.
 
@@ -497,7 +492,7 @@ Python versions.
 
 Useful Tox Commands
 +++++++++++++++++++
-:mod:`tox`  is used to automate common development tasks such as testing, linting, and building documentation.
+:mod:`tox` is used to automate common development tasks such as testing, linting, and building documentation.
 Running :program:`tox` from the project root directory will automatically build virtual environments for all Python interpreters
 found on the system and then install the required packages necessary to perform a given task.  The simplest way to run Tox is:
 

src/sasctl/_services/cas_management.py

@@ -29,9 +29,10 @@ def check_keys(valid_keys: list, input_keys: list, parameters: str):
         String describing the type of parameters
         that are being tested.
 
-    Returns
-    -------
-    raises ValueError if input_keys are not valid
+    Raises
+    ------
+    ValueError 
+        if input_keys are not valid
     """
     if not all(key in valid_keys for key in input_keys):
         raise ValueError(
@@ -55,10 +56,12 @@ def check_required_key(
         String describing the type of parameters
         that are being tested.
 
-    Returns
-    -------
-    raises ValueError if required_key is not present.
-    raises TypeError if required_key is neither a list or a string.
+    Raises
+    ------
+    ValueError
+        if required_key is not present.
+    TypeError
+        if required_key is neither a list or a string.
     """
     if isinstance(required_key, str):
         if required_key not in input_keys:
@@ -93,7 +96,7 @@ def list_sessions(cls, query_params: dict = None, server: str = None):
         Returns a collection of sessions available on the CAS server.
 
         Parameters
-        ------
+        ----------
         query_params : dict, optional
             Query parameters.
             Valid keys are `start`, `limit`, `filter`,
@@ -129,7 +132,7 @@ def create_session(cls, properties: dict, server: str = None):
         """Creates a new session on the CAS server.
 
         Parameters
-        ------
+        ----------
         properties : dict
             Properties of the session.
             Valid keys are `authenticationType` (required),
@@ -164,7 +167,7 @@ def delete_session(
         """Terminates a session on the CAS server.
 
         Parameters
-        ------
+        ----------
         sess_id : str
             A string indicating the Session id.
         server : str
@@ -225,7 +228,7 @@ def get_caslib(cls, name: str, server: str = None):
 
         Returns
         -------
-        RestObj
+        RestObj or None
 
         """
         server = server or DEFAULT_SERVER
@@ -278,7 +281,7 @@ def get_table(cls, name: str, caslib: Union[str, dict] = None, server: str = Non
 
         Returns
         -------
-        RestObj
+        RestObj or None
 
         """
         caslib = caslib or DEFAULT_CASLIB
@@ -309,7 +312,7 @@ def upload_file(
 
         Parameters
         ----------
-        file : str or file-like object
+        file : str or typing.TextIO
             File containing data to upload or path to the file.
         name : str
             Name of the table to create
@@ -321,7 +324,8 @@ def upload_file(
         header : bool, optional
             Whether the first row of data contains column headers.  Defaults to
             True.
-        format_ : {"csv", "xls", "xlsx", "sas7bdat", "sashdat"}, optional
+        format_ : str, optional
+            Choose from {"csv", "xls", "xlsx", "sas7bdat", "sashdat"}.
             File of input `file`.  Not required if format can be discerned from
             the file path.
         detail : dict, optional
@@ -637,6 +641,11 @@ def del_table(
         Returns
         -------
         RestObj
+
+        Raises
+        ------
+        ValueError
+            If `query_params` is empty
         """
 
         server = server or DEFAULT_SERVER

src/sasctl/_services/concepts.py

@@ -37,7 +37,7 @@ def assign_concepts(
 
         Parameters
         ----------
-        documents : str or dict or list_like:
+        documents : str or dict or list
             Documents to analyze.  May be either the URI to a CAS table where the
             documents are currently stored, or an iterable of strings containing
             the documents' text.
@@ -55,8 +55,9 @@ def assign_concepts(
         model
         output_postfix : str, optional
             Text to be added to the end of all output table names.
-        match_type : {'all', 'longest', 'best'}, optional
-            Type of matches to return.  Defaults to 'all'.
+        match_type : str, optional
+            Choose from ``{'all', 'longest', 'best'}``. 
+            Type of matches to return. Defaults to 'all'.
         enable_facts : bool, optional
             Whether to enable facts in the results.  Defaults to False.
         language : str, optional
@@ -71,8 +72,8 @@ def assign_concepts(
 
         See Also
         --------
-        cas_management.get_caslib
-        cas_management.get_table
+        .cas_management.CASManagement.get_caslib
+        .cas_management.CASManagement.get_table
 
         """
         if documents is None:

src/sasctl/_services/data_sources.py

@@ -227,7 +227,7 @@ def table_uri(cls, table):
 
         Parameters
         ----------
-        table : dict or CASTable
+        table : dict or swat.cas.table.CASTable
 
         Returns
         -------

src/sasctl/_services/files.py

@@ -41,13 +41,13 @@ def create_file(cls, file, folder=None, filename=None, expiration=None):
 
         Parameters
         ----------
-        file : str, pathlib.Path, or file_like
+        file : str, pathlib.Path, or typing.BinaryIO
             Path to the file to upload or a file-like object.
         folder : str or dict, optional
-            Name, or, or folder information as returned by :func:`.get_folder`.
+            Name or folder information as returned by :meth:`.get_folder`.
         filename : str, optional
             Name to assign to the uploaded file.  Defaults to the filename if `file` is a path, otherwise required.
-        expiration : datetime, optional
+        expiration : datetime.datetime, optional
             A timestamp that indicates when to expire the file.  Defaults to no expiration.
 
         Returns
@@ -97,7 +97,8 @@ def get_file_content(cls, file):
 
         Returns
         -------
-        content
+        str
+            content
 
         """
         file = cls.get_file(file)

src/sasctl/_services/folders.py

@@ -71,11 +71,12 @@ def get_folder(cls, folder, refresh=False):
         ----------
         folder : str or dict
             May be one of:
-             - folder name
-             - folder ID
-             - folder path
-             - folder delegate string
-             - dictionary representation of the folder
+            
+            - folder name
+            - folder ID
+            - folder path
+            - folder delegate string
+            - dictionary representation of the folder
         refresh : bool, optional
             Obtain an updated copy of the folder.
 

src/sasctl/_services/microanalytic_score.py

@@ -102,12 +102,12 @@ def execute_module_step(cls, module, step, return_dict=True, **kwargs):
         return_dict : bool, optional
             Whether the results should be returned as a dictionary instead
             of a tuple
-        kwargs : any
+        **kwargs
             Passed as arguments to the module step
 
         Returns
         -------
-        any
+        Any
             Results of the step execution.  Returned as a dictionary if
             `return_dict` is True, otherwise returned as a tuple if more
             than one value is returned, otherwise the single value.
@@ -180,8 +180,10 @@ def create_module(
         name : str
         description : str
         source : str
-        language : str { 'python', 'ds2' }
-        scope : str { 'public', 'private' }
+        language : str
+            Choose from ``{'python','ds2'}``
+        scope : str
+            Choose from ``{'public','private'}``
 
         Returns
         -------

src/sasctl/_services/model_management.py

@@ -448,16 +448,16 @@ def create_custom_kpi(
         model : str or dict
             The name or id of the model, or a dictionary representation of the model.
         project : str or dict
-        The name or id of the project, or a dictionary representation of
-        the project.
+            The name or id of the project, or a dictionary representation of
+            the project.
         timeLabel : str or list
             Label associated with the dataset used within the performance definition.
         kpiName : str or list
             Name of the custom KPI.
         kpiValue : int or float or list
             Value of the custom KPI.
-        timeSK : int or list, by default None
-            Indicator for the MM_STD_KPI table to denote performance task order.
+        timeSK : int or list
+            Default is None. Indicator for the MM_STD_KPI table to denote performance task order.
         """
         from .model_repository import ModelRepository
 

src/sasctl/_services/model_publish.py

@@ -230,7 +230,8 @@ def create_destination(
         ----------
         name : str
             Name of the publishing destination.
-        type_ : {'cas', 'mas', 'hadoop', 'teradata'}
+        type_ : str
+            Choose from ``{'cas', 'mas', 'hadoop', 'teradata'}``
             Type of publishing definition being created
         cas_server : str, optional
             Name of the CAS server.  Defaults to 'cas-shared-default'.

src/sasctl/_services/model_repository.py

@@ -65,7 +65,7 @@ def get_astore(cls, model):
 
         Returns
         ----------
-        binary?
+        BinaryIO
 
         """
         # TODO: Download binary object?
@@ -296,10 +296,10 @@ def create_model(
         properties : dict, optional
             Custom model properties provided as name: value pairs.
             Allowed types are int, float, string, datetime.date, and datetime.datetime
-        input_variables : array_like, optional
+        input_variables : Iterable, optional
             Model input variables. By default, these are the same as the model
             project.
-        output_variables : array_like, optional
+        output_variables : Iterable, optional
             Model output variables. By default, these are the same as the model
              project.
         project_version : str
@@ -817,10 +817,10 @@ def list_project_versions(cls, project):
         list of dicts
             List of dicts representing different project versions. Dict key/value
             pairs are as follows.
-                name : str
-                id : str
-                number : str
-                modified : datetime
+            - name : str
+            - id : str
+            - number : str
+            - modified : datetime
 
         """
         project_info = cls.get_project(project)

src/sasctl/_services/saslogon.py

@@ -46,7 +46,7 @@ def create_client(
             The ID to be assigned to the client.
         client_secret : str
             The client secret used for authentication.
-        scopes : list of string, optional
+        scopes : list of str, optional
             Specifies the levels of access that the client will be able to
             obtain on behalf of users when not using client credential
             authentication.  If `allow_password` or `allow_auth_code` are
@@ -160,7 +160,7 @@ def list_clients(cls, start_index=None, count=None, descending=False):
         ----------
         start_index : int, optional
             Index of first client to return.  Defaults to 1.
-        count : int, optiona;
+        count : int, optional
             Number of clients to retrieve.  Defaults to 100.
         descending : bool, optional
             Whether to clients should be returned in descending order.