Merge pull request #154 from OpenProteinAI/feat/autosummary_api_reference

Python Client Documentation Improvements

Author: markgeejw

flake.nix

@@ -18,8 +18,11 @@
         devShells.default = pkgs.mkShell {
           packages = with pkgs; [
             bashInteractive
-            python313Packages.jupytext
+            dprint
           ];
+          shellHook = ''
+            eval $(pixi shell-hook)
+          '';
         };
       }
     );

pixi.lock

@@ -3,14 +3,14 @@ name = "openprotein-docs"
 version = "0.1.0"
 description = "Documentation for OpenProtein"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.8,<3.13"
 classifiers = [
   "Programming Language :: Python :: 3",
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
 ]
 dependencies = [
-  "sphinx>=7.3.0,<7.4.0",
+  "sphinx>=7,<10",
   "pydata-sphinx-theme>=0.16.1,<0.17.0",
   "recommonmark>=0.7.0,<0.8.0",
   "nbsphinx>=0.9.0,<0.10.0",
@@ -19,13 +19,13 @@ dependencies = [
   "sphinx-togglebutton>=0.3.0,<0.4.0",
   "sphinx-copybutton>=0.5.0,<0.6.0",
   "sphinxcontrib-bibtex>=2.6.0,<2.7.0",
-  "swagger_plugin_for_sphinx>=3.5.0,<3.6.0",
   "sphinxcontrib-httpdomain>=1.8.0,<1.9.0",
   "sphinx-new-tab-link>=0.4.0,<0.5.0",
   "sphinx-notfound-page>=1.1.0,<1.2.0",
-  "sphinx-panels>=0.4.1,<0.5.0",
+  "sphinx-design>=0.6.1,<0.7",
   # autodoc
-  "openprotein-python==0.8.12",
+  "openprotein-python==0.9.0",
+  "ipython>=9.8.0,<10",
 ]
 
 [build-system]
@@ -42,7 +42,7 @@ build = "sphinx-build source build"
 [tool.pixi.feature.dev.tasks]
 # install dev version of the client
 dev = "sphinx-autobuild source build --port 5001"
-devinstall = "pip install --no-build-isolation --no-deps --disable-pip-version-check -e ../openprotein-python-private"
+devinstall = "pip install -e ../openprotein-python-private"
 
 [dependency-groups]
 dev = [
@@ -52,6 +52,7 @@ dev = [
   "hatchling>=1.26.1",
   "hatch-vcs>=0.5.0,<1",
   "editables>=0.5,<0.6",
+  "jupytext>=1.18.1,<2",
 ]
 
 [tool.pixi.environments]

pyproject.toml

@@ -16,26 +16,24 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",  # auto pull docstrings
+    "sphinx.ext.napoleon",  # handles numpy/google-style docstrings
     "sphinx.ext.viewcode",
     "recommonmark",
     "sphinx_markdown_tables",
     "sphinx_markdown_builder",
-    "nbsphinx",
+    "nbsphinx",  # renders notebooks
     "sphinx.ext.duration",
     "sphinx.ext.doctest",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",  # generate api reference summary
+    # "sphinx.ext.todo",
     "sphinx_togglebutton",
     "sphinx_copybutton",
     "sphinxcontrib.bibtex",
-    "swagger_plugin_for_sphinx",
     "sphinxcontrib.httpdomain",
     "sphinx_new_tab_link",
     "notfound.extension",
-    "sphinx_panels",
+    "sphinx_design",
 ]
 
 # -- Options for autodoc ----------------------------------------------------
@@ -46,6 +44,8 @@
 # descriptions of the relevant function/method.
 autodoc_typehints = "description"
 
+autodoc_typehints_description_target = "documented"
+
 # Don't show class signature with the class' name.
 autodoc_class_signature = "mixed"
 
@@ -88,7 +88,7 @@
     "header_links_before_dropdown": 6,
     "show_prev_next": False,
     "use_edit_page_button": False,
-    "show_nav_level": 0,
+    # "show_nav_level": 0,
     "navbar_align": "left",
     "navbar_persistent": [
         "search-button",

source/conf.py

@@ -6,13 +6,13 @@ Logging into your account
 
 Log in to the `web platform <https://app.openprotein.ai>`_ with your username and password.
 
-.. image:: ../../_static/getting-started/login.png
+.. image:: /_static/getting-started/login.png
    :width: 500
    :align: center
 
 You can also log in from our `home page <https://openprotein.ai>`_.
 
-.. image:: ../../_static/getting-started/acct-login-homepage.png
+.. image:: /_static/getting-started/acct-login-homepage.png
    :width: 500
    :align: center
 
@@ -26,6 +26,6 @@ Resetting your password
 
 To change your password, navigate to the account icon on the top right corner of the page, and select **Change password**.
 
-.. image:: ../../_static/getting-started/change-password.png
+.. image:: /_static/getting-started/change-password.png
    :width: 700
    :align: center

source/getting-started/account-page.rst

@@ -1,9 +1,9 @@
-.. include:: ./get-started-with-no-code.rst
+.. include:: quickstart-web.rst
 
 .. toctree::
    :hidden:
    :maxdepth: 2
 
-   Get started with no code <get-started-with-no-code>
-   Get started with our API <get-started-with-our-api>
-   Account information <account-page>
+   quickstart-web
+   quickstart-api
+   account-page

source/getting-started/index.rst

@@ -35,6 +35,7 @@ Step 1: Request `early access <https://openprotein-ai.webflow.io/early-access-fo
    Use your username and password credentials generated at sign-up to authenticate your connection to OpenProtein.AI's backend.
 
    .. code-block:: python
+
       import openprotein
 
       with open('secrets.config', 'r') as f:
@@ -83,7 +84,7 @@ Do you want to...
 
    <div class="row mb-3">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/poet-icon.png" height="60px">
+         <img src="/_static/getting-started/poet-icon.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Make sequence predictions or designs without using any data?</b><br/>
@@ -92,7 +93,7 @@ Do you want to...
    </div>
    <div class="row mb-3">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/bar-chart.png" height="60px">
+         <img src="/_static/getting-started/bar-chart.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Analyze your experimental data for library design?</b><br/>
@@ -102,7 +103,7 @@ Do you want to...
    </div>
    <div class="row mb-3">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/dna-broken.png" height="60px">
+         <img src="/_static/getting-started/dna-broken.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Explore your protein's structure?</b><br/>
@@ -111,7 +112,7 @@ Do you want to...
    </div>
    <div class="row">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/embeddings.svg" height="60px">
+         <img src="/_static/getting-started/embeddings.svg" height="60px">
       </div>
       <div class="col-md-10">
          <b>Obtain embeddings from protein language models?</b><br/>

…ing-started/get-started-with-our-api.rst source/getting-started/quickstart-api.rstsource/getting-started/get-started-with-our-api.rst renamed to source/getting-started/quickstart-api.rst source/getting-started/get-started-with-our-api.rst renamed to source/getting-started/quickstart-api.rst

@@ -17,7 +17,7 @@ Quick start tips
 
 Once you log in, you'll see your home view and can navigate to get started with our tools.
 
-.. image:: ../../_static/getting-started/tips.png
+.. image:: /_static/getting-started/tips.png
    :width: 80%
    :align: center
 
@@ -27,7 +27,7 @@ Do you want to...
 
    <div class="row mb-3">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/poet-icon.png" height="60px">
+         <img src="/_static/getting-started/poet-icon.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Make sequence predictions or designs without using any data?</b><br/>
@@ -36,7 +36,7 @@ Do you want to...
    </div>
    <div class="row mb-3">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/bar-chart.png" height="60px">
+         <img src="/_static/getting-started/bar-chart.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Analyze your experimental data for library design?</b><br/>
@@ -46,7 +46,7 @@ Do you want to...
    </div>
    <div class="row">
       <div class="col-md-2 get-started-img">
-         <img src="../_static/getting-started/dna-broken.png" height="60px">
+         <img src="/_static/getting-started/dna-broken.png" height="60px">
       </div>
       <div class="col-md-10">
          <b>Explore your protein's structure?</b><br/>

…ing-started/get-started-with-no-code.rst source/getting-started/quickstart-web.rstsource/getting-started/get-started-with-no-code.rst renamed to source/getting-started/quickstart-web.rst source/getting-started/get-started-with-no-code.rst renamed to source/getting-started/quickstart-web.rst

@@ -3,7 +3,7 @@ openprotein.embeddings
 
 Create embeddings for your protein sequences using open-source and proprietary models!
 
-Note that for PoET Models, you will also need to utilize our :doc:`align <align>` workflow.
+Note that for PoET Models, you will also need to supply a :py:class:`~openprotein.prompt.Prompt`.
 
 Interface 
 ---------
@@ -30,17 +30,44 @@ Models
    :members:
    :inherited-members:
 
-Transform models
+These embedding models inherit from a base :py:class:`~openprotein.embeddings.EmbeddingModel`, due to their shared functionality in providing the :py:meth:`~openprotein.embeddings.EmbeddingModel.embed` method. These can also be used to fit the :ref:`transform-models`.
+
+.. autoclass:: openprotein.embeddings.EmbeddingModel
+   :members: 
+
+.. _transform-models:
+
+Transform Models
 ^^^^^^^^^^^^^^^^
 
-These models are overlaid on top of the base embeddings models to produce reduced/transformed embeddings. Refer to their detailed documentation in `openprotein.svd <./svd.rst#openprotein.svd.SVDModel>`_ and `openprotein.umap <./umap.rst#openprtein.umap.UMAPModel>`_.
+These models are overlaid on top of the base embeddings models to produce reduced/transformed embeddings. 
+
+:py:class:`~openprotein.svd.SVDModel` represents an SVD model which is suitable to reduce the high-dimensional embeddings returned by base embedding models, whilst maintaining semantic information, fitted on your :py:class:`~openprotein.data.AssayDataset`. You can fit your own SVD from any model's :py:meth:`~openprotein.embeddings.EmbeddingModel.fit_svd`.  
 
 .. autoclass:: openprotein.svd.SVDModel
+   :members:
+   :inherited-members:
+
+:py:class:`~openprotein.umap.UMAPModel` represents a UMAP model which is suitable to project the high-dimensional embeddings into a lower dimension (usually 2) for visualization, to understand the semantic grouping within your :py:class:`~openprotein.data.AssayDataset`. You can fit your own UMAP from any model's :py:meth:`~openprotein.embeddings.EmbeddingModel.fit_umap`.  
 
 .. autoclass:: openprotein.umap.UMAPModel
+   :members:
+   :inherited-members:
+
+Reduction methods
+^^^^^^^^^^^^^^^^^
+
+Foundational embedding models also take an optional reduction to use simple pooling methods:
+
+.. autoclass:: openprotein.common.ReductionType()
+   :members:
+
+.. note::
+
+   By default, the :py:meth:`~openprotein.embeddings.EmbeddingModel.embed` method uses the :py:attr:`~openprotein.common.ReductionType.MEAN` reduction to reduce network load. You have to explicitly pass ``reduction=None`` to get full-sized embeddings.
 
 Results
----------
+-------
 
 .. autoclass:: openprotein.embeddings.EmbeddingsResultFuture
    :members:
@@ -54,9 +81,3 @@ Results
    :members:
    :inherited-members:
 
-Base model
-----------
-
-The base embedding model is the base class of all the embedding models.
-
-.. autoclass:: openprotein.embeddings.EmbeddingModel