--wip--

.github/workflows/ci.yaml

@@ -50,3 +50,18 @@ jobs:
           cache: 'pip'
       - run: make deps
       - run: make build
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          check-latest: true
+          cache: 'pip'
+      - uses: quarto-dev/quarto-actions/setup@v2
+      - uses: quarto-dev/quarto-actions/render@v2
+      - run: make deps
+      - run: make dev
+      - run: make docs

Makefile

@@ -78,7 +78,7 @@ test:
 
 # Target for uninstalling the project
 uninstall:
-	$(PIP) uninstall -y $(NAME)
+	$(PIP) uninstall $(NAME)
 
 # Target for displaying the project version
 version:

docs/_quarto.yml

@@ -9,7 +9,7 @@ website:
         file: installation.qmd
       - text: Quick Start
         file: quickstart.qmd
-      - text: Reference
+      - text: API
         file: reference/index.qmd
 
 filters:
@@ -18,8 +18,8 @@ filters:
 format:
   html:
     theme: cosmo
-    css: styles.css
     toc: true
+    page-layout: full
 
 interlinks:
   sources:
@@ -35,7 +35,6 @@ quartodoc:
   package: posit
   render_interlinks: true
   options:
-      include_attributes: true
       include_classes: true
       include_functions: true
       include_empty: true
@@ -47,22 +46,23 @@ quartodoc:
       contents:
         - name: connect.Client
           members:
-            - content
-            - metrics
-            - tasks
-            - users
+            # methods
             - request
             - get
             - post
             - put
             - patch
             - delete
-    - title: Posit Connect
+    - title: Posit Connect Resources
       package: posit
       contents:
         - connect.bundles
         - connect.content
-        - connect.metrics.Metrics
         - connect.permissions
         - connect.tasks
         - connect.users
+    - title: Posit Connect Metrics
+      package: posit
+      contents:
+        - connect.metrics
+        - connect.metrics.usage

src/posit/connect/bundles.py

@@ -1,18 +1,31 @@
-"""Bundle resource interface."""
+"""Bundle resources."""
 
 from __future__ import annotations
 
 import io
-
 import requests
-
 from typing import List
-
 from . import config, resources, tasks, urls
 
 
 class BundleMetadata(resources.Resource):
-    """Bundle metadata interface."""
+    """Bundle metadata resource.
+
+    Attributes
+    ----------
+    source : str | None
+        Source of the bundle.
+    source_repo : str | None
+        Source repository of the bundle.
+    source_branch : str | None
+        Source branch of the bundle.
+    source_commit : str | None
+        Source commit of the bundle.
+    archive_md5 : str | None
+        MD5 checksum of the bundle archive.
+    archive_sha1 : str | None
+        SHA-1 checksum of the bundle archive.
+    """
 
     @property
     def source(self) -> str | None:
@@ -40,7 +53,37 @@ def archive_sha1(self) -> str | None:
 
 
 class Bundle(resources.Resource):
-    """Bundle interface."""
+    """Bundle resource.
+
+    Attributes
+    ----------
+    id : str
+        Identifier of the bundle.
+    content_guid : str
+        Content GUID of the bundle.
+    created_time : str
+        Creation time of the bundle.
+    cluster_name : str | None
+        Cluster name associated with the bundle.
+    image_name : str | None
+        Image name of the bundle.
+    r_version : str | None
+        R version used in the bundle.
+    r_environment_management : bool | None
+        Indicates if R environment management is enabled.
+    py_version : str | None
+        Python version used in the bundle.
+    py_environment_management : bool | None
+        Indicates if Python environment management is enabled.
+    quarto_version : str | None
+        Quarto version used in the bundle.
+    active : bool | None
+        Indicates if the bundle is active.
+    size : int | None
+        Size of the bundle.
+    metadata : BundleMetadata
+        Metadata of the bundle.
+    """
 
     @property
     def id(self) -> str:
@@ -96,9 +139,8 @@ def metadata(self) -> BundleMetadata:
             self.config, self.session, **self.get("metadata", {})
         )
 
-    # CRUD Methods
-
     def delete(self) -> None:
+        """Delete the bundle."""
         path = f"v1/content/{self.content_guid}/bundles/{self.id}"
         url = urls.append(self.config.url, path)
         self.session.delete(url)
@@ -126,14 +168,14 @@ def deploy(self) -> tasks.Task:
         ts = tasks.Tasks(self.config, self.session)
         return ts.get(result["task_id"])
 
-    def download(self, output: io.BufferedWriter | str):
+    def download(self, output: io.BufferedWriter | str) -> None:
         """Download a bundle.
 
         Download a bundle to a file or memory.
 
         Parameters
         ----------
-        output: io.BufferedWriter | str
+        output : io.BufferedWriter or str
             An io.BufferedWriter instance or a str representing a relative or absolute path.
 
         Raises
@@ -154,7 +196,7 @@ def download(self, output: io.BufferedWriter | str):
         """
         if not isinstance(output, (io.BufferedWriter, str)):
             raise TypeError(
-                f"download() expected argument type 'io.BufferedWriter` or 'str', but got '{type(input).__name__}'"
+                f"download() expected argument type 'io.BufferedWriter` or 'str', but got '{type(output).__name__}'"
             )
 
         path = f"v1/content/{self.content_guid}/bundles/{self.id}/download"
@@ -163,16 +205,30 @@ def download(self, output: io.BufferedWriter | str):
         if isinstance(output, io.BufferedWriter):
             for chunk in response.iter_content():
                 output.write(chunk)
-            return
-
-        if isinstance(output, str):
+        elif isinstance(output, str):
             with open(output, "wb") as file:
                 for chunk in response.iter_content():
                     file.write(chunk)
-            return
 
 
 class Bundles(resources.Resources):
+    """Bundles resource.
+
+    Parameters
+    ----------
+    config : config.Config
+        Configuration object.
+    session : requests.Session
+        HTTP session object.
+    content_guid : str
+        Content GUID associated with the bundles.
+
+    Attributes
+    ----------
+    content_guid: str
+        Content GUID associated with the bundles.
+    """
+
     def __init__(
         self,
         config: config.Config,
@@ -183,13 +239,14 @@ def __init__(
         self.content_guid = content_guid
 
     def create(self, input: io.BufferedReader | bytes | str) -> Bundle:
-        """Create a bundle.
+        """
+        Create a bundle.
 
         Create a bundle from a file or memory.
 
         Parameters
         ----------
-        input : io.BufferedReader | bytes | str
+        input : io.BufferedReader, bytes, or str
             Input archive for bundle creation. A 'str' type assumes a relative or absolute filepath.
 
         Returns
@@ -236,24 +293,45 @@ def create(self, input: io.BufferedReader | bytes | str) -> Bundle:
         return Bundle(self.config, self.session, **result)
 
     def find(self) -> List[Bundle]:
+        """Find all bundles.
+
+        Returns
+        -------
+        list of Bundle
+            List of all found bundles.
+        """
         path = f"v1/content/{self.content_guid}/bundles"
         url = urls.append(self.config.url, path)
         response = self.session.get(url)
         results = response.json()
         return [
-            Bundle(
-                self.config,
-                self.session,
-                **result,
-            )
-            for result in results
+            Bundle(self.config, self.session, **result) for result in results
         ]
 
     def find_one(self) -> Bundle | None:
+        """Find a bundle.
+
+        Returns
+        -------
+        Bundle | None
+            The first found bundle | None if no bundles are found.
+        """
         bundles = self.find()
         return next(iter(bundles), None)
 
     def get(self, id: str) -> Bundle:
+        """Get a bundle.
+
+        Parameters
+        ----------
+        id : str
+            Identifier of the bundle to retrieve.
+
+        Returns
+        -------
+        Bundle
+            The bundle with the specified ID.
+        """
         path = f"v1/content/{self.content_guid}/bundles/{id}"
         url = urls.append(self.config.url, path)
         response = self.session.get(url)