clear most docstrings reference warnings

Author: SilvestriStefano

doc/conf.py

@@ -50,17 +50,26 @@
 ]
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
+    "python": ("https://docs.python.org/3/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", 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://requests.readthedocs.io/en/latest/", None),
-    "tox": ("https://tox.readthedocs.io/en/latest/", None),
-    "flake8": ("http://flake8.pycqa.org/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_param = False
+napoleon_use_rtype = False
+
 todo_include_todos = True
 
 todo_emit_warnings = True
@@ -92,6 +101,9 @@
 # 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','Response'),('py:class','Request'),('py:class','sasctl._services.service.Service')]
 
 # -- 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

@@ -58,8 +58,10 @@ def check_required_key(
 
     Raises
     ------
-    ValueError if required_key is not present.
-    TypeError if required_key is neither a list or a string.
+    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:
@@ -310,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

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_like
             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.
@@ -71,8 +71,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

@@ -43,7 +43,7 @@ def create_file(cls, file, folder=None, filename=None, expiration=None):
         file : str or file_like
             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
@@ -96,7 +96,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,7 +102,7 @@ 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
@@ -180,8 +180,8 @@ def create_module(
         name : str
         description : str
         source : str
-        language : str { 'python', 'ds2' }
-        scope : str { 'public', 'private' }
+        language : {'python','ds2'}
+        scope : {'public','private'}
 
         Returns
         -------

src/sasctl/_services/model_management.py

@@ -456,8 +456,8 @@ def create_custom_kpi(
             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_repository.py

@@ -813,10 +813,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/sentiment_analysis.py

@@ -37,7 +37,7 @@ def analyze_sentiment(
 
         Parameters
         ----------
-        documents : str or dict or list_like:
+        documents : str or dict or Iterable:
             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.
@@ -67,8 +67,8 @@ def analyze_sentiment(
 
         See Also
         --------
-        cas_management.get_caslib
-        cas_management.get_table
+        .cas_management.CASManagement.get_caslib
+        .cas_management.CASManagement.get_table
 
         """
         if current_session().version_info() >= 4:

src/sasctl/_services/service.py

@@ -78,7 +78,7 @@ def request(cls, verb, path, session=None, format_="auto", **kwargs):
             text: Response.text
             auto: `RestObj` constructed from JSON if possible, otherwise same as
                   `text`.
-        kwargs : any
+        **kwargs
             Additional arguments are passed to the session `request` method.
 
         Returns
@@ -369,7 +369,7 @@ def _get_rel(cls, item, rel, *args, func=None, filter_=None):
         ----------
         item : str or dict
         rel : str
-        args : any
+        *args
             Passed to `func`
         func : function, optional
             Callable that takes (item, *args) and returns a RestObj of `item`
@@ -408,7 +408,7 @@ def _monitor_job(cls, job, max_retries=60):
 
         Returns
         -------
-        job
+        job : dict
 
         Raises
         ------

src/sasctl/_services/text_categorization.py

@@ -60,8 +60,8 @@ def categorize(
 
         See Also
         --------
-        cas_management.get_caslib
-        cas_management.get_table
+        .cas_management.CASManagement.get_caslib
+        .cas_management.CASManagement.get_table
 
         """
         if current_session().version_info() >= 4:

src/sasctl/_services/text_parsing.py

@@ -16,10 +16,10 @@ class TextParsing(Service):
     Parsing is a key operation in understanding your data. Parsing a document
     involves the following analyses:
 
-     - Identifying terms used in the document
-     - Recognizing parts of speech for each term
-     - Identifying which terms are entities (person, country, and so on)
-     - Resolving synonyms, misspellings, and so on
+    - Identifying terms used in the document
+    - Recognizing parts of speech for each term
+    - Identifying which terms are entities (person, country, and so on)
+    - Resolving synonyms, misspellings, and so on
 
     The output tables that are generated during parsing can also be used in
     downstream analyses such as topic generation.
@@ -97,8 +97,8 @@ def parse_documents(
 
         See Also
         --------
-        cas_management.get_caslib
-        cas_management.get_table
+        .cas_management.CASManagement.get_caslib
+        .cas_management.CASManagement.get_table
 
         """
         if current_session().version_info() >= 4: