Improve API reference organization, copy, and appearance

Author: gustavocidornelas

docs/requirements.txt

@@ -1,6 +1,6 @@
 numpydoc
-pydata-sphinx-theme==0.8.1
-sphinx>=4.5.0
+pydata-sphinx-theme==0.14.1
+sphinx>=7.2.6
 # These packages cause 'make' to break
 protobuf==3.20.2
 pygments>=2.7.0

docs/source/_static/img/openlayer-white.svg

@@ -21,7 +21,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Openlayer Python API reference"
-copyright = "2022, Unbox Inc."
+copyright = "2023, Openlayer"
 author = "Openlayer"
 
 # The short X.Y version
@@ -57,7 +57,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 master_doc = "index"
@@ -101,17 +101,17 @@
     "github_url": "https://github.com/openlayer-ai/examples-gallery",
     "twitter_url": "https://twitter.com/openlayerco",
     # "google_analytics_id": "UA-27880019-2",
-    "navbar_end": ["version-switcher", "navbar-icon-links"],
-    "switcher": {
-        # "json_url": "https://pandas.pydata.org/versions.json",
-        "url_template": "https://openlayer.com/docs/{version}/",
-        "version_match": switcher_version,
-    },
+    "navbar_end": ["navbar-icon-links"],
+    # "switcher": {
+    #     # "json_url": "https://pandas.pydata.org/versions.json",
+    #     # "url_template": "https://openlayer.com/docs/{version}/",
+    #     # "version_match": switcher_version,
+    # },
 }
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "_static/img/openlayer.svg"
+html_logo = "_static/img/openlayer-white.svg"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/source/conf.py

@@ -5,19 +5,16 @@
 
 .. module:: openlayer
 
-***********************
-Openlayer Documentation
-***********************
+*********************************
+Openlayer Python Client reference
+*********************************
 
 **Date**: |today| **Version**: |version|
 
 Welcome to the API documentation for `Openlayer <https://openlayer.com>`__!
 
 These docs cover our official Python library, which you may use to interact with the Openlayer platform.
 
-If you are new to Openlayer, or looking for more general documentation, including an introduction to the platform and in-depth tutorials,
-please navigate `here <https://docs.openlayer.com>`__.
-
 Installation
 ============
 

docs/source/index.rst

@@ -0,0 +1,19 @@
+.. _api.authentication:
+
+==============
+Authentication
+==============
+.. currentmodule:: openlayer
+
+Openlayer uses API keys for client authentication. You can find your workspace API key on
+your `Account settings <https://docs.openlayer.com/docs/find-your-api-keys>`_.
+
+The authentication step happens when the ``OpenlayerClient`` is instantiated.
+
+Client
+------
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   OpenlayerClient

docs/source/reference/authentication.rst

@@ -0,0 +1,95 @@
+.. _api.development:
+
+===========
+Development
+===========
+.. currentmodule:: openlayer
+
+The development mode of a project helps you as you iterate on your models and datasets.
+You will use the methods described on this page to add models and datasets to your
+development project,
+
+To use these methods, you must have:
+
+1. Authenticated, using :obj:`openlayer.OpenlayerClient`
+
+2. Created a project, using :obj:`openlayer.OpenlayerClient.create_project`
+
+**Related guide**: `How to upload datasets and models for development <https://docs.openlayer.com/docs/upload-datasets-and-models>`_.
+
+
+Staging area
+------------
+The upload of models and datasets to a project on Openlayer follows a similar flow
+to the one for uploading files to a version control system like Git.
+
+The ``add_*`` methods, add models and datasets to the local staging area.
+As you add resources to the staging area, you can check its status using the
+``status`` method.
+
+
+Finally, the resources on the staging area are committed and pushed to the Openlayer
+platform using the ``commit`` and ``push`` methods.
+
+
+Datasets
+--------
+Datasets stored as Pandas dataframes or csv files can be easily added to a project's
+staging area with the methods below.
+
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   Project.add_dataset
+   Project.add_dataframe
+
+Models
+------
+Models are added to the staging area using the ``add_model`` method.
+
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   Project.add_model
+
+Committing and pushing
+----------------------
+After adding resources to the staging area, you can commit and push them to Openlayer.
+
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   Project.commit
+   Project.push
+
+Other methods to interact with the staging area
+-----------------------------------------------
+Additional methods used to interact with the staging area.
+
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   Project.status
+   Project.restore
+   Project.export
+
+Checking a project version's goal statuses
+------------------------------------------
+To programatically check the status of a project version's goals, use the
+``ProjectVersion`` object, which can be obtained using the ``load_project_version`` method.
+
+.. autosummary::
+   :toctree: api/
+   :template: class.rst
+
+   ProjectVersion
+   OpenlayerClient.load_project_version
+
+
+
+
+

docs/source/reference/development.rst

@@ -4,17 +4,40 @@
 API reference
 =============
 
-This page gives an overview of all public ``openlayer`` objects, functions and methods.
+This API reference has the technical description of the ``openlayer`` Python client API
+and shows how to operate it.
 
+If you are new to Openlayer, or looking for the full product documentation, including
+an introduction to the platform and in-depth tutorials, please navigate
+`here <https://docs.openlayer.com>`_.
+
+Installation
+============
+
+The :mod:`openlayer` library is available on PyPI and conda-forge, and can be installed
+with:
+
+.. code:: console
+
+   $ pip install openlayer
+
+.. code:: console
+
+   $ conda install openlayer --channel conda-forge
+
+
+Section Navigation
+==================
 
 .. toctree::
    :maxdepth: 2
 
+   authentication
    projects
-   evaluation
+   development
    monitoring
-   validate
-   objects
+..    validate
+..    objects
 
 .. meta::
     :description lang=en:

docs/source/reference/evaluation.rst

@@ -5,30 +5,54 @@ Monitoring
 ==========
 .. currentmodule:: openlayer
 
+The monitoring mode of a project helps you keep track of model health in production and
+set up alert for when your model is not performing as expected.
+You will use the methods described on this page to create an inference pipeline, publish
+production data, and upload reference datasets.
+
+To use these methods, you must have:
+
+1. Authenticated, using :obj:`openlayer.OpenlayerClient`
+
+2. Created a project, using :obj:`openlayer.OpenlayerClient.create_project`
+
+**Related guide**: `How to set up monitoring <https://docs.openlayer.com/docs/set-up-monitoring>`_.
+
 
 Creating and loading inference pipelines
 ----------------------------------------
+The inference pipeline represents a model deployed in production. It is part of an
+Openlayer project is what enables the monitoring mode.
+
 .. autosummary::
    :toctree: api/
    :template: class.rst
 
-   OpenlayerClient.create_inference_pipeline
-   OpenlayerClient.load_inference_pipeline
+   Project.create_inference_pipeline
+   Project.load_inference_pipeline
 
-Uploading reference datasets
+Publishing production data
 ----------------------------
+Production data is published to an inference pipeline on the Openlayer platform using
+the methods below.
+
 .. autosummary::
    :toctree: api/
    :template: class.rst
 
-   OpenlayerClient.upload_reference_dataset
-   OpenlayerClient.upload_reference_dataframe
+   InferencePipeline.publish_batch_data
+   InferencePipeline.publish_ground_truths
 
-Publishing production data
+Uploading reference datasets
 ----------------------------
+Reference datasets can be uploaded to an inference pipeline to enable data drift goals.
+The production data will be compared to the reference dataset to measure
+drift.
+
 .. autosummary::
    :toctree: api/
    :template: class.rst
 
-   OpenlayerClient.publish_batch_data
-   OpenlayerClient.publish_ground_truths
+   InferencePipeline.upload_reference_dataset
+   InferencePipeline.upload_reference_dataframe
+