ODSC-44446. Multiple fixes to documentation (#264)

Author: liudmylaru

docs/source/ads.explanations.rst

@@ -0,0 +1,2 @@
+ads.explanations package
+========================

docs/source/ads.jobs.rst

@@ -1,12 +1,6 @@
 ads.jobs package
 ================
 
-.. toctree::
-   :maxdepth: 3
-
-   ads.jobs
-
-
 Subpackages
 -----------
 

docs/source/conf.py

@@ -173,3 +173,11 @@
 todo_include_todos = True
 
 mathjax_path = "math_jax_3_2_0.js"
+
+# This css will be included in htlm pages to process where we add .. raw:: html for nb cell nice outputs with
+# <div class="nboutput nblast docutils container"> and
+# <div class="output_area rendered_html docutils container">
+# See ads_tuner.rst dataframe output in .. raw:: html sections
+html_css_files = [
+    "nbsphinx-code-cells.css"
+]

docs/source/index.rst

@@ -97,6 +97,7 @@ Oracle Accelerated Data Science (ADS)
    `https://github.com/oracle/accelerated-data-science <https://github.com/oracle/accelerated-data-science>`_
 
 .. code-block:: python3
+
    >>> import ads
    >>> ads.hello()
 

docs/source/user_guide/big_data_service/file_management.rst

@@ -71,7 +71,7 @@ Upload
 ------
 
 The `.put() <https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.put>`_ method is used to upload files from local storage to HDFS. The first parameter is the local path of the files to upload. The second parameter is the HDFS path where the files are to be stored. 
-`.upload() <https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.upload>`_ is an alias of `.put()`.
+`.upload() <https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.upload>`_ is an alias of ``.put()``.
 .. code-block:: python3
 
     fs.put(
@@ -82,7 +82,7 @@ The `.put() <https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.sp
 Ibis
 ====
 
-`Ibis <https://github.com/ibis-project/ibis>`_ is an open-source library by `Cloudera <https://www.cloudera.com/>`_ that provides a Python framework to access data and perform analytical computations from different sources. Ibis allows access to the data ising HDFS. You use the ``ibis.impala.hdfs_connect()`` method to make a connection to HDFS, and it returns a handler. This handler has methods such as ``.ls()`` to list, ``.get()`` to download, ``.put()`` to upload, and ``.rm()`` to delete files. These operations support globbing. Ibis' HDFS connector supports a variety of `additional operations <https://ibis-project.org/docs/dev/backends/Impala/#hdfs-interaction>`_.
+`Ibis <https://github.com/ibis-project/ibis>`_ is an open-source library by `Cloudera <https://www.cloudera.com/>`_ that provides a Python framework to access data and perform analytical computations from different sources. Ibis allows access to the data ising HDFS. You use the ``ibis.impala.hdfs_connect()`` method to make a connection to HDFS, and it returns a handler. This handler has methods such as ``.ls()`` to list, ``.get()`` to download, ``.put()`` to upload, and ``.rm()`` to delete files. These operations support globbing. Ibis' HDFS connector supports a variety of `additional operations <https://ibis-project.org/backends/impala/#hdfs-interaction>`_.
 
 Connect
 -------
@@ -159,7 +159,7 @@ Use the `.put() <https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspe
 Pandas
 ======
 
-Pandas allows access to BDS' HDFS system through :ref: `FSSpec`. This section demonstrates some common operations.
+Pandas allows access to BDS' HDFS system through :ref:`FSSpec`. This section demonstrates some common operations.
 
 Connect
 -------
@@ -259,4 +259,3 @@ The following sample code shows several different PyArrow methods for working wi
     table = pa.Table.from_pandas(df)
     pq.write_to_dataset(table, root_path="/path/on/BDS/HDFS", partition_cols=["dt"], 
                         flavor="spark", filesystem=fs)
-

docs/source/user_guide/big_data_service/sql_data_management.rst

@@ -13,7 +13,7 @@ Ibis
 Connect
 -------
 
-Obtaining a Kerberos ticket, depending on your system configuration, you may need to define the ``ibis.options.impala.temp_db`` and ``ibis.options.impala.temp_hdfs_path`` options. The ``ibis.impala.connect()`` method makes a connection to the `Impala execution backend <https://ibis-project.org/docs/dev/backends/Impala/>`_. The ``.sql()`` allows you to run SQL commands on the data.
+Obtaining a Kerberos ticket, depending on your system configuration, you may need to define the ``ibis.options.impala.temp_db`` and ``ibis.options.impala.temp_hdfs_path`` options. The ``ibis.impala.connect()`` method makes a connection to the `Impala execution backend <https://ibis-project.org/backends/impala/>`_. The ``.sql()`` allows you to run SQL commands on the data.
 
 .. code-block:: python3
 
@@ -167,5 +167,3 @@ It is important to close sessions when you don't need them anymore. This frees u
 .. code-block:: python3
 
     cursor.close()
-
-

docs/source/user_guide/data_transformation/data_transformation.rst

@@ -20,12 +20,27 @@ You can load a ``pandas`` dataframe into an ``ADSDataset`` by calling.
 Automated Transformations
 *************************
 
-ADS has built in automatic transform tools for datasets. When the ``get_recommendations()`` tool is applied to an ``ADSDataset`` object, it shows the user detected issues with the data and recommends changes to apply to the dataset.  You can accept the changes is as easy as clicking a button in the drop down menu.  After all the changes are applied, the transformed dataset can be retrieved by calling ``get_transformed_dataset()``.
+ADS provides built-in automatic transformation tools for datasets. These tools help detect issues with the data and recommend changes to improve the dataset. The recommended changes can be accepted by clicking a button in the drop-down menu. Once the changes are applied, the transformed dataset can be retrieved using the ``get_transformed_dataset()`` method.
+
+To access the recommendations, you can use the ``get_recommendations()`` method on the ``ADSDataset`` object:
 
 .. code-block:: python3
 
+  wine_ds = DatasetFactory.from_dataframe(data, target='Price') # Specify the target variable
   wine_ds.get_recommendations()
 
+However, please note that ``get_recommendations()`` is not a direct method of the ``ADSDataset`` class. If you created the dataset using ``ADSDataset.from_dataframe(data)``, calling ``get_recommendations()`` directly on the ``ADSDataset`` object will result in an error. Instead, you can retrieve the recommendations by following these steps:
+
+.. code-block:: python3
+
+  from ads.dataset.factory import DatasetFactory
+
+  wine_ds = DatasetFactory.from_dataframe(data, target='Price')
+  # Get the recommendations
+  recommendations = wine_ds.get_recommendations()
+
+The ``recommendations`` variable will contain the detected issues with the dataset and the recommended changes. You can then review and accept the recommended changes as needed.
+
 Alternatively, you can use ``auto_transform()`` to apply all the recommended transformations at once. ``auto_transform()`` returns a transformed dataset with several optimizations applied automatically. The optimizations include:
 
 * Dropping constant and primary key columns, which has no predictive quality.
@@ -242,7 +257,7 @@ You can apply functions to update column values in existing column. This example
 Change Data Type
 ================
 
-You can change the data type columns with the ``astype()`` method. ADS uses the Pandas method, ``astype()``, on dataframe objects. For specifics, see `astype for a Pandas Dataframe <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.astype.html>`_, `using numpy.dtype <https://docs.scipy.org/doc/numpy/reference/generated/numpy.dtype.html#numpy.dtype>`_, or `Pandas dtypes <https://pandas.pydata.org/pandas-docs/stable/getting_started/basics.html#dtypes>`_.
+You can change the data type columns with the ``astype()`` method. ADS uses the Pandas method, ``astype()``, on dataframe objects. For specifics, see `astype for a Pandas Dataframe <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.astype.html>`_, `using numpy.dtype <https://docs.scipy.org/doc/numpy/reference/generated/numpy.dtype.html#numpy.dtype>`_, or `Pandas dtypes <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.dtypes.html>`_.
 
 When you change the type of a column, ADS updates its semantic type to categorical, continuous, datetime, or ordinal. For example, if you update a column type to integer, its semantic type updates to ordinal.  For data type details, see ref:`loading-data-specify-dtype`.