Update Python API reference docs based on latest GraphQL schema (#282)

The main contribution of this PR is to update the Python API reference
docs with the new classes added in the recent schema change
(`TomogramAuthor` and `AnnotationFile`).

In addition, there are few other documentation related changes.

1\. Updated quick start to reflect other API changes (e.g. removing
`binning` keyword argument from `download_mrcfile`).

2\. Added the upgrade option to the napari plugin, so that its
dependencies (like the Python client in this repo) are upgraded when
there is an existing installation.

3\. Fixed the examples in the base model so that they work with the
current schema.

4\. Fixed some typos and small mistakes in the model docstrings.

5\. Enforced a version of Sphinx pre v7 to prevent an error when
building the HTML docs.

The error is `Reason: UndefinedError("'style' is undefined")` and is
likely related to the Sphinx RTD theme not supporting Sphinx v7. The
[corresponding
issue](readthedocs/readthedocs.org#10279)
should be fixed for v2 of the theme, but I did not find that to be the
case.

client/python/cryoet_data_portal/src/cryoet_data_portal/_gql_base.py

@@ -239,18 +239,18 @@ def find(
             query_filters:
                 A set of expressions that narrow down the search results
 
-        Returns:
-            A list of matching Model objects.
+        Yields:
+            Matching Model objects.
 
         Examples:
 
             Filter runs by attributes, including attributes in related models:
 
-            >>> runs_list = Runs.find(client, query_filters=[Runs.camera_model == "K2 Summit", Runs.tomograms.size_x > 900])
+            >>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
 
             Get all results for this type:
 
-            >>> runs_object = Runs.find(client)
+            >>> runs = Run.find(client)
         """
         filters = {}
         if query_filters:
@@ -269,12 +269,12 @@ def get_by_id(cls, client: Client, id: int):
                 Unique identifier for the object
 
         Returns:
-            A matching Model object.
+            A matching Model object if found, None otherwise.
 
         Examples:
             Get a Run by ID:
 
-            >>> run = Runs.get_by_id(client), 1
+            >>> run = Run.get_by_id(client, 1)
                 print(run.name)
         """
         results = cls.find(client, [cls.id == id])

client/python/cryoet_data_portal/src/cryoet_data_portal/_models.py

@@ -29,7 +29,7 @@ class Dataset(Model):
         cell_type_id (str): Cell Ontology identifier for the cell type
         dataset_citations (str): DOIs for publications that cite the dataset. Use a comma to separate multiple DOIs.
         dataset_publications (str): DOIs for publications that describe the dataset. Use a comma to separate multiple DOIs.
-        deposition_date: date! Date when a dataset is initially received by the Data Portal.
+        deposition_date: Date when a dataset is initially received by the Data Portal.
         description (str): A short description of a CryoET dataset, similar to an abstract for a journal article or dataset.
         funding_sources: List[FundingSource] An array relationship with FundingSource
         grid_preparation (str): Describe Cryo-ET grid preparation.
@@ -41,7 +41,7 @@ class Dataset(Model):
         organism_taxid (str): NCBI taxonomy identifier for the organism, e.g. 9606
         other_setup (str): Describe other setup not covered by sample preparation or grid preparation that may make this dataset unique in  the same publication
         related_database_entries (str): If a CryoET dataset is also deposited into another database, enter the database identifier here (e.g. EMPIAR-11445). Use a comma to separate multiple identifiers.
-        related_database_links (str): If a CryoET dataset is also deposited into another database, e.g. EMPAIR, enter the database identifier here (e.g.https://www.ebi.ac.uk/empiar/EMPIAR-12345/).  Use a comma to separate multiple links.
+        related_database_links (str): If a CryoET dataset is also deposited into another database, e.g. EMPIAR, enter the database identifier here (e.g.https://www.ebi.ac.uk/empiar/EMPIAR-12345/).  Use a comma to separate multiple links.
         release_date (date): Date when a dataset is made available on the Data Portal.
         runs: List[Run] An array relationship with Run
         s3_prefix (str): The S3 public bucket path where this dataset is contained
@@ -115,9 +115,9 @@ class DatasetAuthor(Model):
         affiliation_name (str): Name of the institutions an author is affiliated with. Comma separated
         author_list_order(int): The order in which the author appears in the publication
         corresponding_author_status (bool):Indicating whether an author is the corresponding author
-        dataset (Dataset): An object relationship with the dataset this author correspods to
+        dataset (Dataset): An object relationship with the dataset this author corresponds to
         dataset_id (int): Numeric identifier for the dataset this author corresponds to
-        email (str): Email address for each autho
+        email (str): Email address for each author
         name (str): Full name of a dataset author (e.g. Jane Doe).
         primary_author_status (bool): Indicating whether an annotator is the main person executing the annotation, especially on manual annotation
         orcid (str): A unique, persistent identifier for researchers, provided by ORCID.
@@ -145,7 +145,7 @@ class DatasetFunding(Model):
 
     Attributes:
         id (int): A numeric identifier for this funding record
-        dataset (Dataset): An object relationship with the dataset this funding source correspods to
+        dataset (Dataset): An object relationship with the dataset this funding source corresponds to
         dataset_id (int): Numeric identifier for the dataset this funding source corresponds to
         funding_agency_name (str): Name of the funding agency.
         grant_id (str): Grant identifier provided by the funding agency.
@@ -263,7 +263,7 @@ class Tomogram(Model):
         dataset_id (int): Reference to the dataset this tomogram is a part of
         fiducial_alignment_status (str): Fiducial Alignment status: True = aligned with fiducial False = aligned without fiducial
         https_mrc_scale0 (str): HTTPS path to this tomogram in MRC format (no scaling)
-        https_omezarr_dir (str): HTTPS path to the this multiscale omezarr tomogram
+        https_omezarr_dir (str): HTTPS path to this tomogram in multiscale OME-Zarr format
         is_canonical (bool): Is this tomogram considered the canonical tomogram for the run experiment? True=Yes
         key_photo_url (str): URL for the key photo
         key_photo_thumbnail_url (str): URL for the thumbnail of key photo
@@ -274,10 +274,10 @@ class Tomogram(Model):
         offset_z (int):  z offset data relative to the canonical tomogram in pixels
         processing (str): Describe additional processing used to derive the tomogram
         processing_software (str): Processing software used to derive the tomogram
-        reconstruction_method (str):Describe reconstruction method (Weighted backprojection, SART, SIRT)
+        reconstruction_method (str):Describe reconstruction method (Weighted back-projection, SART, SIRT)
         reconstruction_software (str):Name of software used for reconstruction
         s3_mrc_scale0 (str):S3 path to this tomogram in MRC format (no scaling)
-        s3_omezarr_dir (str):S3 path to the this multiscale omezarr tomogram
+        s3_omezarr_dir (str):S3 path to this tomogram in multiscale OME-Zarr format
         scale0_dimensions (str):comma separated x,y,z dimensions of the unscaled tomogram
         scale1_dimensions (str):comma separated x,y,z dimensions of the scale1 tomogram
         scale2_dimensions (str):comma separated x,y,z dimensions of the scale2 tomogram
@@ -335,7 +335,7 @@ class Tomogram(Model):
     )
 
     def download_omezarr(self, dest_path: Optional[str] = None):
-        """Download the omezarr version of this tomogram
+        """Download the OME-Zarr version of this tomogram
 
         Args:
             dest_path (Optional[str], optional): Choose a destination directory. Defaults to $CWD.
@@ -564,7 +564,7 @@ class TiltSeries(Model):
         https_angle_list (str): HTTPS path to the angle list file for this tiltseries
         https_collection_metadata (str): HTTPS path to the collection metadata file for this tiltseries
         https_mrc_bin1 (str): HTTPS path to this tiltseries in MRC format (no scaling)
-        https_omezarr_dir (str): HTTPS path to the this multiscale omezarr tiltseries
+        https_omezarr_dir (str): HTTPS path to this tomogram in multiscale OME-Zarr format
         microscope_additional_info (str):  Other microscope optical setup information, in addition to energy filter, phase plate and image corrector
         microscope_energy_filter: (str): Energy filter setup used
         microscope_image_corrector (str): Image corrector setup
@@ -576,7 +576,7 @@ class TiltSeries(Model):
         s3_angle_list (str): S3 path to the angle list file for this tiltseries
         s3_collection_metadata (str): S3 path to the collection metadata file for this tiltseries
         s3_mrc_bin1 (str): S3 path to this tiltseries in MRC format (no scaling)
-        s3_omezarr_dir (str): S3 path to the this multiscale omezarr tiltseries
+        s3_omezarr_dir (str): S3 path to this tomogram in multiscale OME-Zarr format
         spherical_aberration_constant (float): Spherical Aberration Constant of the objective lens in millimeters
         tilt_axis (float): Rotation angle in degrees
         tilt_max (float): Maximal tilt angle in degrees

docs/cryoet_data_portal_docsite_napari.md

@@ -122,7 +122,7 @@ We also built [a plugin that lets you browse the CryoET Data Portal in napari](h
 This plugin can be installed from PyPI by running
 
 ```shell
-pip install napari-cryoet-data-portal
+pip install -U napari-cryoet-data-portal
 ```
 
 After installation, navigate to napari's *Plugins* menu and click on the *CryoET Data Portal* item to open the browser.

docs/cryoet_data_portal_docsite_quick_start.md

@@ -86,8 +86,8 @@ for tomo in tomos:
     # Print the tomogram metadata as a json string
     print(json.dumps(tomo.to_dict(), indent=4))
 
-    # Download a 25% size preview image (uncomment to actually download files)
-    # tomo.download_mrcfile(binning=4)
+    # Download a tomogram in the MRC format (uncomment to actually download files)
+    # tomo.download_mrcfile()
 ```
 
 Downloads display a progress bar by default:

docs/python-api.rst

@@ -55,12 +55,24 @@ Tomogram
    :members:
    :inherited-members:
 
+TomogramAuthor
+--------------
+.. autoclass:: cryoet_data_portal.TomogramAuthor
+   :members:
+   :inherited-members:
+
 Annotation
 --------------
 .. autoclass:: cryoet_data_portal.Annotation
    :members:
    :inherited-members:
 
+AnnotationFile
+--------------
+.. autoclass:: cryoet_data_portal.AnnotationFile
+   :members:
+   :inherited-members:
+
 AnnotationAuthor
 ----------------
 .. autoclass:: cryoet_data_portal.AnnotationAuthor

docs/requirements.txt

@@ -1,3 +1,4 @@
+sphinx<7
 nbsphinx
 myst-parser
 sphinx-rtd-theme