fix up theme work for docs (#153)

darenr · web-flow · commit 5738f9f0283c · 2023-04-25T14:30:05.000-07:00
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,11 +2,10 @@ autodoc
 nbsphinx
 sphinx
 sphinxcontrib-napoleon
-sphinx-rtd-theme
 sphinx_copybutton
 sphinx_code_tabs
 sphinx-autobuild
-sphinx-design
+sphinx-autorun
 oracle_ads
 furo
 IPython
diff --git a/docs/source/_static/logo-light-mode.png b/docs/source/_static/logo-light-mode.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,21 +23,20 @@
 version = release = __import__("ads").__version__
 
 extensions = [
-    "sphinx_rtd_theme",
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
-    "sphinx.ext.todo",
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
-    "sphinx.ext.graphviz",
-    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.autodoc",
     "sphinx.ext.todo",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",    
+    "sphinx.ext.graphviz",
     "nbsphinx",
     "sphinx_code_tabs",
-    "sphinx_design",
-    "sphinx_copybutton"
+    "sphinx_copybutton",
+    "sphinx_autorun",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -65,30 +64,28 @@
 # exclude_patterns = []
 exclude_patterns = ['build', '**.ipynb_checkpoints', 'Thumbs.db', '.DS_Store']
 
-# The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = "sphinx"
-# pygments_dark_style = "monokai"
-
 language = "en"
 
 html_theme = "furo"
 html_static_path = ["_static"]
 
+html_title = f"{project} v{release}"
+
+# Disable the generation of the various indexes
+html_use_modindex = False
+html_use_index = False
+
+# html_css_files = [
+#     'pied-piper-admonition.css',     
+# ]
+
 html_theme_options = {
     "light_logo": "logo-light-mode.png",
-    "dark_logo": "logo-dark-mode.png",
+    "dark_logo": "logo-dark-mode.png",     
 }
 
-html_css_files = [
-    'pied-piper-admonition.css',     
-]
-htmlhelp_basename = "pydoc"
-
-# banner
 
-# html_theme_options = {
-#     "announcement": "<em>Important</em> announcement!",
-# }
+htmlhelp_basename = "pydoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,8 +6,8 @@
         library and CLI for Machine learning engineers to work with Cloud Infrastructure (CPU and GPU VMs, Storage etc, Spark) for Data, Models,
         Notebooks, Pipelines and Jobs.
 
-Oracle Accelerated Data Science SDK (ADS)
-=========================================
+Oracle Accelerated Data Science (ADS)
+=====================================
 |PyPI|_ |Python|_ |Notebook Examples|_
 
 .. |PyPI| image:: https://img.shields.io/pypi/v/oracle-ads.svg?style=for-the-badge&logo=pypi&logoColor=white
@@ -67,46 +67,43 @@ Oracle Accelerated Data Science SDK (ADS)
    modules
 
 .. admonition:: Oracle Accelerated Data Science (ADS)
+   :class: note
 
-  Oracle Accelerated Data Science (ADS) is maintained by the Oracle Cloud Infrastructure Data Science service team. It speeds up common data science activities by providing tools that automate and/or simplify common data science tasks, along with providing a data scientist friendly pythonic interface to Oracle Cloud Infrastructure (OCI) services, most notably OCI Data Science, Data Flow, Object Storage, and the Autonomous Database. ADS gives you an interface to manage the lifecycle of machine learning models, from data acquisition to model evaluation, interpretation, and model deployment.
+   Oracle Accelerated Data Science (ADS) is maintained by the Oracle Cloud Infrastructure Data Science service team. It speeds up common data science activities by providing tools that automate and/or simplify common data science tasks, along with providing a data scientist friendly pythonic interface to Oracle Cloud Infrastructure (OCI) services, most notably OCI Data Science, Data Flow, Object Storage, and the Autonomous Database. ADS gives you an interface to manage the lifecycle of machine learning models, from data acquisition to model evaluation, interpretation, and model deployment.
 
-  With ADS you can:
+   With ADS you can:
 
-    - Read datasets from Oracle Object Storage, Oracle RDBMS (ATP/ADW/On-prem), AWS S3, and other sources into Pandas dataframes.
-    - Easily compute summary statistics on your dataframes and perform data profiling.
-    - Tune models using hyperparameter optimization with the ADSTuner tool.
-    - Generate detailed evaluation reports of your model candidates with the ADSEvaluator module.
-    - Save machine learning models to the OCI Data Science Models.
-    - Deploy those models as HTTPS endpoints with Model Deployment.
-    - Launch distributed ETL, data processing, and model training jobs in Spark with OCI Data Flow.
-    - Train machine learning models in OCI Data Science Jobs.
-    - Manage the lifecycle of conda environments through the ads conda command line interface (CLI).
-    - Distributed Training with PyTorch, Horovod and Dask
+   - Read datasets from Oracle Object Storage, Oracle RDBMS (ATP/ADW/On-prem), AWS S3, and other sources into Pandas dataframes.
+   - Easily compute summary statistics on your dataframes and perform data profiling.
+   - Tune models using hyperparameter optimization with the ADSTuner tool.
+   - Generate detailed evaluation reports of your model candidates with the ADSEvaluator module.
+   - Save machine learning models to the OCI Data Science Models.
+   - Deploy those models as HTTPS endpoints with Model Deployment.
+   - Launch distributed ETL, data processing, and model training jobs in Spark with OCI Data Flow.
+   - Train machine learning models in OCI Data Science Jobs.
+   - Manage the lifecycle of conda environments through the ads conda command line interface (CLI).
+   - Distributed Training with PyTorch, Horovod and Dask
 
 
 .. admonition:: Installation
+   :class: note
 
    python3 -m pip install oracle-ads
 
 
 .. admonition:: Source Code
+   :class: note
 
    `https://github.com/oracle/accelerated-data-science <https://github.com/oracle/accelerated-data-science>`_
 
-.. code:: ipython3
-
+.. code-block:: python3
    >>> import ads
    >>> ads.hello()
 
-     O  o-o   o-o
-    / \ |  \ |
-   o---o|   O o-o
-   |   ||  /     |
-   o   oo-o  o--o
+.. runblock:: pycon
 
-   ADS SDK version: X.Y.Z
-   Pandas version: x.y.z
-   Debug mode: False
+   >>> import ads
+   >>> ads.hello()
 
 
 Additional Documentation
@@ -115,6 +112,8 @@ Additional Documentation
   - `OCI Data Science and AI services Examples <https://github.com/oracle/oci-data-science-ai-samples>`_
   - `Oracle AI & Data Science Blog <https://blogs.oracle.com/ai-and-datascience/>`_
   - `OCI Documentation <https://docs.oracle.com/en-us/iaas/data-science/using/data-science.htm>`_
+  - `OCIFS Documentation <https://ocifs.readthedocs.io/en/latest/>`_
+  - `Example Notebooks <https://github.com/oracle-samples/oci-data-science-ai-samples/tree/master/notebook_examples>`_
 
 Examples
 ++++++++
@@ -147,25 +146,25 @@ This example uses SQL injection safe binding variables.
 
 .. code-block:: python3
 
-  import ads
-  import pandas as pd
+   import ads
+   import pandas as pd
 
-  connection_parameters = {
+   connection_parameters = {
       "user_name": "<user_name>",
       "password": "<password>",
       "service_name": "<tns_name>",
       "wallet_location": "<file_path>",
-  }
+   }
 
-  df = pd.DataFrame.ads.read_sql(
+   df = pd.DataFrame.ads.read_sql(
       """
       SELECT *
       FROM SH.SALES
       WHERE ROWNUM <= :max_rows
       """,
       bind_variables={ max_rows : 100 },
       connection_parameters=connection_parameters,
-  )
+   )
 
 More Examples
 ~~~~~~~~~~~~~
diff --git a/docs/source/user_guide/apachespark/dataflow-spark-magic.rst b/docs/source/user_guide/apachespark/dataflow-spark-magic.rst
@@ -79,6 +79,7 @@ Use the `%help` method to get a list of all the available commands, along with a
   %help
 
 .. admonition:: Tip
+   :class: note
 
   To access the docstrings of any magic command and figure out what arguments to provide, simply add ``?`` at the end of the command. For instance: ``%create_session?``
 
diff --git a/docs/source/user_guide/apachespark/dataflow.rst b/docs/source/user_guide/apachespark/dataflow.rst
@@ -41,6 +41,7 @@ Define config. If you have not yet configured your dataflow setting, or would li
 Use the config defined above to submit the cell.
 
 .. admonition:: Tip
+   :class: note
 
   Get more information about the dataflow extension by running ``%dataflow -h``
 
@@ -131,11 +132,13 @@ To submit your notebook to DataFlow using the ``ads`` CLI, run:
   ads opctl run -s <folder where notebook is located> -e <notebook name> -b dataflow
 
 .. admonition:: Tip
+   :class: note
 
   You can avoid running cells that are not DataFlow environment compatible by tagging the cells and then providing the tag names to ignore. In the following example cells that are tagged ``ignore`` and ``remove`` will be ignored -
   ``--exclude-tag ignore --exclude-tag remove``
 
 .. admonition:: Tip
+   :class: note
 
   You can run the notebook in your local pyspark environment before submitting to ``DataFlow`` using the same CLI with ``-b local``
 
diff --git a/docs/source/user_guide/apachespark/spark.rst b/docs/source/user_guide/apachespark/spark.rst
@@ -4,6 +4,7 @@ Apache Spark
 
 
 .. admonition:: DataFlow
+   :class: note
 
   Oracle Cloud Infrastructure (OCI) Data Flow is a fully managed, serverless, and on-demand Apache Spark Service that performs data processing or model training tasks on extremely large datasets without infrastructure to deploy or manage.
 
diff --git a/docs/source/user_guide/cli/opctl/localdev/condapack.rst b/docs/source/user_guide/cli/opctl/localdev/condapack.rst
@@ -25,6 +25,7 @@ create
 Build conda packs from your workstation using ``ads opctl conda create`` subcommand.
 
 .. admonition:: Tip
+   :class: note
 
     To publish a conda pack that is natively installed on a oracle linux host (compute or laptop), use ``NO_CONTAINER`` environment variable to remove dependency on the ml-job container image:
 
diff --git a/docs/source/user_guide/jobs/data_science_job.rst b/docs/source/user_guide/jobs/data_science_job.rst
@@ -2,6 +2,7 @@ Quick Start
 ***********
 
 .. admonition:: Prerequisite
+  :class: note
 
   Before creating a job, ensure that you have policies configured for Data Science resources.
 
diff --git a/docs/source/user_guide/jobs/policies.rst b/docs/source/user_guide/jobs/policies.rst
@@ -11,6 +11,7 @@ This section describe the policies you might need for running Data Science Jobs.
     You should further restrict the access to the resources base on your needs.
 
 .. admonition:: Policy subject
+    :class: note
 
     In the following example, ``group <your_data_science_users>`` is the subject of the policy
     when using OCI API keys for authentication. For resource principal authentication,
diff --git a/docs/source/user_guide/jobs/run_container.rst b/docs/source/user_guide/jobs/run_container.rst
@@ -4,6 +4,7 @@ Run a Container
 The :py:class:`~ads.jobs.ContainerRuntime` class allows you to run a container image using OCI data science jobs.
 
 .. admonition:: OCI Container Registry
+  :class: note
 
   To use the :py:class:`~ads.jobs.ContainerRuntime`, you need to first push the image to
   `OCI container registry <https://docs.oracle.com/en-us/iaas/Content/Registry/Concepts/registryoverview.htm>`_.
diff --git a/docs/source/user_guide/jobs/run_git.rst b/docs/source/user_guide/jobs/run_git.rst
@@ -34,6 +34,7 @@ For repository on GitHub, you could setup the
 `GitHub Deploy Key <https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys>`_ as secret.
 
 .. admonition:: Git Version for Private Repository
+  :class: note
 
   Git version of 2.3+ is required to use a private repository.
 
diff --git a/docs/source/user_guide/loading_data/connect_legacy.rst b/docs/source/user_guide/loading_data/connect_legacy.rst
@@ -2,14 +2,15 @@ Connect with ``DatasetFactory``
 *******************************
 
 
-.. admonition:: Deprecation Note |deprecated|
+.. admonition:: |deprecated|
+  :class: note
 
-    * ``DataSetFactory.open`` is deprecated in favor of Pandas to read from file systems. 
-    * Pandas(>1.2.1) can connect to object storage using uri format - ``oci://bucket@namepace/path/to/data``.
-    * To read from Oracle database or MySQL, see DataBase sections under :doc:`Connecting to Datasources<connect>`
-    * ``DataSetFactory.from_dataframe`` is supported to create ``ADSDataset`` class from ``pandas`` dataframe
+  * ``DataSetFactory.open`` is deprecated in favor of Pandas to read from file systems. 
+  * Pandas(>1.2.1) can connect to object storage using uri format - ``oci://bucket@namepace/path/to/data``.
+  * To read from Oracle database or MySQL, see DataBase sections under :doc:`Connecting to Datasources<connect>`
+  * ``DataSetFactory.from_dataframe`` is supported to create ``ADSDataset`` class from ``pandas`` dataframe
 
-    See :doc:`Connecting to Datasources<connect>` for examples.
+  See :doc:`Connecting to Datasources<connect>` for examples.
 
 .. |deprecated| image:: /_static/badge_deprecated.svg
 
diff --git a/docs/source/user_guide/model_registration/_template/deploy.rst b/docs/source/user_guide/model_registration/_template/deploy.rst
@@ -6,7 +6,8 @@ See `API documentation <../../ads.model.html#id1>`__ for more details about the
 
 
 .. admonition:: Tips
+   :class: note
 
-    * Providing ``deployment_access_log_id`` and ``deployment_predict_log_id`` helps in debugging your model inference setup.
-    * Default Load Balancer configuration has bandwidth of 10 Mbps. `Refer service document to help you choose the right setup. <https://docs.oracle.com/en-us/iaas/data-science/using/model_dep_create.htm>`_ 
-    * Check for supported instance shapes `here <https://docs.oracle.com/en-us/iaas/data-science/using/overview.htm#supported-shapes>`_ .
+   * Providing ``deployment_access_log_id`` and ``deployment_predict_log_id`` helps in debugging your model inference setup.
+   * Default Load Balancer configuration has bandwidth of 10 Mbps. `Refer service document to help you choose the right setup. <https://docs.oracle.com/en-us/iaas/data-science/using/model_dep_create.htm>`_ 
+   * Check for supported instance shapes `here <https://docs.oracle.com/en-us/iaas/data-science/using/overview.htm#supported-shapes>`_ .
diff --git a/docs/source/user_guide/model_training/automl/quick_start.rst b/docs/source/user_guide/model_training/automl/quick_start.rst
@@ -2,6 +2,7 @@ Quick Start
 ===========
 
 .. admonition:: Prerequisite
+    :class: note
 
     You need to check if AutoMLx library is installed in your environment. For more information on the conda environments that contain AutoMLx, check `this page <https://docs.oracle.com/en-us/iaas/data-science/using/conda-automlx-fam.htm>`__.
 
diff --git a/docs/source/user_guide/model_training/distributed_training/configuration/configuration.rst b/docs/source/user_guide/model_training/distributed_training/configuration/configuration.rst
@@ -29,6 +29,7 @@ OCI Policies
 Several OCI policies are needed for distributed training.
 
 .. admonition:: Policy subject
+  :class: note
 
   In the following example, ``group <your_data_science_users>`` is the subject of the policy. When starting the job from an OCI notebook session using resource principal, the subject should be ``dynamic-group``, for example, ``dynamic-group <your_notebook_sessions>``
 
diff --git a/docs/source/user_guide/model_training/distributed_training/dask/dask.rst b/docs/source/user_guide/model_training/distributed_training/dask/dask.rst
@@ -9,6 +9,7 @@ creating both the container and ``yaml`` spec to run the distributed workload.
 
 
 .. admonition:: Dask
+  :class: note
 
   This is a good choice when you want to use ``Scikit-Learn``, ``XGBoost``, ``LightGBM`` or have
   data parallel tasks for very large datasets where the data can be partitioned. 
diff --git a/docs/source/user_guide/model_training/distributed_training/developer/developer.rst b/docs/source/user_guide/model_training/distributed_training/developer/developer.rst
@@ -9,6 +9,7 @@ Build Image
 -----------
 
 .. admonition:: Tip
+    :class: note
 
     Use `-h` option to see options and usage help
 
@@ -73,6 +74,7 @@ Run the container Image on the OCI Data Science or local
 --------------------------------------------------------
 
 .. admonition:: Tip
+    :class: note
 
     Use `-h` option to see options and usage help
 
diff --git a/docs/source/user_guide/model_training/distributed_training/overview.rst b/docs/source/user_guide/model_training/distributed_training/overview.rst
@@ -3,6 +3,7 @@ Distributed Training
 ====================
 
 .. admonition:: Distributed Training with OCI Data Science
+  :class: note
 
   This documentation shows you how to preprocess, and train on a machine
   learning model, using Oracle Cloud Infrastructure. This section will not teach you about distributed training, 
diff --git a/docs/source/user_guide/model_training/distributed_training/remote_source_code.rst b/docs/source/user_guide/model_training/distributed_training/remote_source_code.rst
@@ -3,10 +3,11 @@ Run Source Code from Git or Object Storage
 ==========================================
 
 .. admonition:: Require ADS >=2.6.3
+  :class: note
 
-    Running source code from Git or Object Storage requires ADS 2.6.3 or newer.
+  Running source code from Git or Object Storage requires ADS 2.6.3 or newer.
 
-    ``python3 -m pip install oracle-ads>=2.6.3 --upgrade``
+  ``python3 -m pip install oracle-ads>=2.6.3 --upgrade``
 
 Instead of adding the training source code to the docker image, you can also fetch the code at runtime from Git repository or object storage.
 
diff --git a/docs/source/user_guide/pipeline/quick_start.rst b/docs/source/user_guide/pipeline/quick_start.rst

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@ Apache Spark`
`4`	`4`
`5`	`5`
`6`	`6`	`.. admonition:: DataFlow`
	`7`	`+ :class: note`
`7`	`8`
`8`	`9`	`Oracle Cloud Infrastructure (OCI) Data Flow is a fully managed, serverless, and on-demand Apache Spark Service that performs data processing or model training tasks on extremely large datasets without infrastructure to deploy or manage.`
`9`	`10`