docs(samples): use autodoc_pydantic for Pydantic model docs

Replaces autoclass with autopydantic_model directives so that model
fields render with their type, description, and required status in a
single entry — instead of the previous duplicated Parameters/Fields
sections and the misleading (**data) signature.

Field descriptions are moved from :param: docstrings into
Field(description=...) so autodoc_pydantic can pick them up directly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mhusbynflow

flowbio/v2/samples.py

@@ -31,7 +31,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from tqdm import tqdm
 
 from flowbio.v2._pagination import PageIterator
@@ -45,35 +45,22 @@
 class SampleType(BaseModel, frozen=True):
     """A type of sample that can be uploaded to the Flow platform.
 
-    :param identifier: Unique identifier for this sample type.
-    :param name: Human-readable display name.
-    :param description: Explanation of what this sample type represents.
-
     Example::
 
         sample_types = client.samples.get_types()
         for st in sample_types:
             print(f"{st.identifier}: {st.name}")
     """
 
-    identifier: str
-    name: str
-    description: str
+    identifier: str = Field(description="Unique identifier for this sample type.")
+    name: str = Field(description="Human-readable display name.")
+    description: str = Field(description="Explanation of what this sample type represents.")
 
 
 class MetadataAttribute(BaseModel, frozen=True):
     """A metadata attribute that can be attached to a sample. See :ref:`metadata-attributes` for a more detailed
     explanation.
 
-    :param identifier: Unique identifier for this attribute.
-    :param name: Human-readable display name.
-    :param description: Explanation of what this attribute represents.
-    :param required: Whether this attribute is required at sample creation.
-    :param required_for_sample_types: Sample type identifiers for which
-        this attribute is required at creation.
-    :param options: The list of valid values, or ``None`` if any value
-        is accepted.
-
     Example::
 
         attributes = client.samples.get_metadata_attributes()
@@ -82,75 +69,64 @@ class MetadataAttribute(BaseModel, frozen=True):
                 print(f"{attr.name}: choose from {attr.options}")
     """
 
-    identifier: str
-    name: str
-    description: str
-    required: bool
-    required_for_sample_types: list[str]
-    options: list[str] | None
+    identifier: str = Field(description="Unique identifier for this attribute.")
+    name: str = Field(description="Human-readable display name.")
+    description: str = Field(description="Explanation of what this attribute represents.")
+    required: bool = Field(description="Whether this attribute is required at sample creation.")
+    required_for_sample_types: list[str] = Field(
+        description="Sample type identifiers for which this attribute is required at creation.",
+    )
+    options: list[str] | None = Field(
+        description="The list of valid values, or ``None`` if any value is accepted.",
+    )
 
 
 class Project(BaseModel, frozen=True):
     """A project that samples can be assigned to.
 
-    :param id: Unique identifier for this project.
-    :param name: Human-readable display name.
-    :param description: Explanation of what this project is for.
-
     Example::
 
         projects = client.samples.get_owned_projects()
         for p in projects:
             print(f"{p.id}: {p.name}")
     """
 
-    id: str
-    name: str
-    description: str
+    id: str = Field(description="Unique identifier for this project.")
+    name: str = Field(description="Human-readable display name.")
+    description: str = Field(description="Explanation of what this project is for.")
 
 
 class Organism(BaseModel, frozen=True):
     """An organism that a sample can be associated with.
 
-    :param id: Unique identifier for this organism.
-    :param name: Common name.
-    :param latin_name: Scientific (Latin) name.
-
     Example::
 
         organisms = client.samples.get_organisms()
         for o in organisms:
             print(f"{o.id}: {o.name} ({o.latin_name})")
     """
 
-    id: str
-    name: str
-    latin_name: str
+    id: str = Field(description="Unique identifier for this organism.")
+    name: str = Field(description="Common name.")
+    latin_name: str = Field(description="Scientific (Latin) name.")
 
 
 class Sample(BaseModel, frozen=True):
     """A sample on the Flow platform. For now this only includes id, but when we
     add more methods to retrieve samples with more detail, more fields will be added.
-
-
-    :param id: The unique identifier of the sample.
     """
 
-    id: str
+    id: str = Field(description="The unique identifier of the sample.")
 
 
 class MultiplexedUpload(BaseModel, frozen=True):
-    """Result of a multiplexed data upload.
+    """Result of a multiplexed data upload."""
 
-    :param data_ids: IDs for the uploaded multiplexed reads data.
-    :param annotation_id: ID for the uploaded annotation data.
-    :param warnings: Annotation warnings returned by the server.
-        Empty if the annotation was accepted without warnings.
-    """
-
-    data_ids: list[str]
-    annotation_id: str
-    warnings: list[dict]
+    data_ids: list[str] = Field(description="IDs for the uploaded multiplexed reads data.")
+    annotation_id: str = Field(description="ID for the uploaded annotation data.")
+    warnings: list[dict] = Field(
+        description="Annotation warnings returned by the server. Empty if the annotation was accepted without warnings.",
+    )
 
 
 class SampleResource:

source/conf.py

@@ -21,8 +21,17 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
+    "sphinxcontrib.autodoc_pydantic",
 ]
 
+autodoc_pydantic_model_hide_paramlist = True
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_field_show_alias = False
+autodoc_pydantic_field_doc_policy = "description"
+
 templates_path = ['_templates']
 exclude_patterns = []
 

source/v2/samples.rst

@@ -175,20 +175,14 @@ API Reference
 Models
 ------
 
-.. autoclass:: flowbio.v2.samples.Sample
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.Sample
 
-.. autoclass:: flowbio.v2.samples.SampleType
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.SampleType
 
-.. autoclass:: flowbio.v2.samples.MetadataAttribute
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.MetadataAttribute
 
-.. autoclass:: flowbio.v2.samples.Project
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.Project
 
-.. autoclass:: flowbio.v2.samples.Organism
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.Organism
 
-.. autoclass:: flowbio.v2.samples.MultiplexedUpload
-   :no-members:
+.. autopydantic_model:: flowbio.v2.samples.MultiplexedUpload