docs: update api documentation to show all resources (#370)

Author: tdstein

docs/Makefile

@@ -7,7 +7,7 @@ CURRENT_YEAR ?= $(shell date +%Y)
 # Quarto settings
 QUARTO ?= quarto
 # quartodoc doesn't like py3.8; Run using `--with` as it can conflict with the project's dependencies
-QUARTODOC ?= --with "quartodoc==0.8.1" quartodoc
+QUARTODOC ?= --no-cache --with "quartodoc==0.8.1" quartodoc
 
 # Netlify settings
 NETLIFY_SITE_ID ?= 5cea1f56-7935-4387-975a-18a7905d15ee

docs/_quarto.yml

@@ -94,20 +94,29 @@ quartodoc:
             - put
             - patch
             - delete
-    - title: Posit Connect Resources
+    - title: Resources
       contents:
         - connect.bundles
         - connect.content
+        - connect.env
+        - connect.environments
         - connect.groups
+        - connect.jobs
+        - connect.metrics
+        - connect.metrics.usage
+        - connect.oauth
+        - connect.oauth.associations
+        - connect.oauth.integrations
+        - connect.oauth.sessions
+        - connect.packages
         - connect.permissions
+        - connect.repository
+        - connect.system
+        - connect.tags
         - connect.tasks
         - connect.users
         - connect.vanities
-    - title: Posit Connect Metrics
-      contents:
-        - connect.metrics
-        - connect.metrics.usage
-    - title: External Integrations
+    - title: Third-Party Integrations
       contents:
         - connect.external.databricks
         - connect.external.snowflake

src/posit/connect/client.py

@@ -11,8 +11,8 @@
 from .content import Content
 from .context import Context, ContextManager, requires
 from .groups import Groups
-from .metrics import Metrics
-from .oauth import OAuth
+from .metrics.metrics import Metrics
+from .oauth.oauth import OAuth
 from .resources import _PaginatedResourceSequence, _ResourceSequence
 from .system import System
 from .tags import Tags
@@ -43,18 +43,30 @@ class Client(ContextManager):
     ----------
     content: Content
         Content resource.
+    environments: Environments
+        Environments resource.
+    groups: Groups
+        Groups resource.
     me: User
-        Connect user resource.
+        Current user resource.
     metrics: Metrics
         Metrics resource.
     oauth: OAuth
         OAuth resource.
+    packages: Packages
+        Packages resource.
+    system: System
+        System resource.
+    tags: Tags
+        Tags resource.
     tasks: Tasks
         Tasks resource.
     users: Users
         Users resource.
+    vanities: Vanities
+        Vanities resource.
     version: str
-        Server version.
+        The server version.
     """
 
     @overload
@@ -162,28 +174,21 @@ def __init__(self, *args, **kwargs) -> None:
         self._ctx = Context(self)
 
     @property
-    def version(self) -> str | None:
+    def content(self) -> Content:
         """
-        The server version.
+        The content resource interface.
 
         Returns
         -------
-        str
-            The version of the Posit Connect server.
+        Content
+            The content resource instance.
         """
-        return self._ctx.version
+        return Content(self._ctx)
 
     @property
-    def me(self) -> User:
-        """
-        The connected user.
-
-        Returns
-        -------
-        User
-            The currently authenticated user.
-        """
-        return me.get(self._ctx)
+    @requires(version="2023.05.0")
+    def environments(self) -> Environments:
+        return _ResourceSequence(self._ctx, "v1/environments")
 
     @property
     def groups(self) -> Groups:
@@ -197,40 +202,66 @@ def groups(self) -> Groups:
         return Groups(self._ctx)
 
     @property
-    def tasks(self) -> Tasks:
+    def me(self) -> User:
         """
-        The tasks resource interface.
+        The connected user.
 
         Returns
         -------
-        tasks.Tasks
-            The tasks resource instance.
+        User
+            The currently authenticated user.
         """
-        return Tasks(self._ctx)
+        return me.get(self._ctx)
 
     @property
-    def users(self) -> Users:
+    def metrics(self) -> Metrics:
         """
-        The users resource interface.
+        The Metrics API interface.
+
+        The Metrics API is designed for capturing, retrieving, and managing
+        quantitative measurements of Connect interactions. It is commonly used
+        for monitoring and analyzing system performance, user behavior, and
+        business processes. This API facilitates real-time data collection and
+        accessibility, enabling organizations to make informed decisions based
+        on key performance indicators (KPIs).
 
         Returns
         -------
-        Users
-            The users resource instance.
+        Metrics
+            The metrics API instance.
+
+        Examples
+        --------
+        >>> from posit import connect
+        >>> client = connect.Client()
+        >>> content_guid = "2243770d-ace0-4782-87f9-fe2aeca14fc8"
+        >>> events = client.metrics.usage.find(content_guid=content_guid)
+        >>> len(events)
+        24
         """
-        return Users(self._ctx)
+        return Metrics(self._ctx)
 
     @property
-    def content(self) -> Content:
+    @requires(version="2024.08.0")
+    def oauth(self) -> OAuth:
         """
-        The content resource interface.
+        The OAuth API interface.
 
         Returns
         -------
-        Content
-            The content resource instance.
+        OAuth
+            The oauth API instance.
         """
-        return Content(self._ctx)
+        return OAuth(self._ctx, self.cfg.api_key)
+
+    @property
+    @requires(version="2024.11.0")
+    def packages(self) -> Packages:
+        return _PaginatedResourceSequence(self._ctx, "v1/packages", uid="name")
+
+    @property
+    def system(self) -> System:
+        return System(self._ctx, "v1/system")
 
     @property
     def tags(self) -> Tags:
@@ -255,63 +286,44 @@ def tags(self) -> Tags:
         return Tags(self._ctx, "v1/tags")
 
     @property
-    def metrics(self) -> Metrics:
+    def tasks(self) -> Tasks:
         """
-        The Metrics API interface.
-
-        The Metrics API is designed for capturing, retrieving, and managing
-        quantitative measurements of Connect interactions. It is commonly used
-        for monitoring and analyzing system performance, user behavior, and
-        business processes. This API facilitates real-time data collection and
-        accessibility, enabling organizations to make informed decisions based
-        on key performance indicators (KPIs).
+        The tasks resource interface.
 
         Returns
         -------
-        Metrics
-            The metrics API instance.
-
-        Examples
-        --------
-        >>> from posit import connect
-        >>> client = connect.Client()
-        >>> content_guid = "2243770d-ace0-4782-87f9-fe2aeca14fc8"
-        >>> events = client.metrics.usage.find(content_guid=content_guid)
-        >>> len(events)
-        24
+        tasks.Tasks
+            The tasks resource instance.
         """
-        return Metrics(self._ctx)
+        return Tasks(self._ctx)
 
     @property
-    @requires(version="2024.08.0")
-    def oauth(self) -> OAuth:
+    def users(self) -> Users:
         """
-        The OAuth API interface.
+        The users resource interface.
 
         Returns
         -------
-        OAuth
-            The oauth API instance.
+        Users
+            The users resource instance.
         """
-        return OAuth(self._ctx, self.cfg.api_key)
-
-    @property
-    @requires(version="2024.11.0")
-    def packages(self) -> Packages:
-        return _PaginatedResourceSequence(self._ctx, "v1/packages", uid="name")
+        return Users(self._ctx)
 
     @property
     def vanities(self) -> Vanities:
         return Vanities(self._ctx)
 
     @property
-    def system(self) -> System:
-        return System(self._ctx, "v1/system")
+    def version(self) -> str | None:
+        """
+        The server version.
 
-    @property
-    @requires(version="2023.05.0")
-    def environments(self) -> Environments:
-        return _ResourceSequence(self._ctx, "v1/environments")
+        Returns
+        -------
+        str
+            The version of the Posit Connect server.
+        """
+        return self._ctx.version
 
     def __del__(self):
         """Close the session when the Client instance is deleted."""

src/posit/connect/env.py

@@ -1,3 +1,5 @@
+"""Environment variable resources."""
+
 from __future__ import annotations
 
 from typing_extensions import TYPE_CHECKING, Any, Iterator, List, Mapping, MutableMapping, Optional

src/posit/connect/environments.py

@@ -1,3 +1,5 @@
+"""Environment resources."""
+
 from __future__ import annotations
 
 from abc import abstractmethod

src/posit/connect/external/__init__.py

@@ -1 +1,6 @@
-# NOTE: The APIs in this module are provided as a convenience and are subject to breaking changes.
+"""External integrations.
+
+Notes
+-----
+The APIs in this module are provided as a convenience and are subject to breaking changes.
+"""

src/posit/connect/external/databricks.py

@@ -1,7 +1,10 @@
-"""
+"""Databricks SDK integration.
+
 Databricks SDK credentials implementations which support interacting with Posit OAuth integrations on Connect.
 
-NOTE: These APIs are provided as a convenience and are subject to breaking changes:
+Notes
+-----
+These APIs are provided as a convenience and are subject to breaking changes:
 https://github.com/databricks/databricks-sdk-py#interface-stability
 """
 

src/posit/connect/external/snowflake.py

@@ -1,6 +1,10 @@
-"""Snowflake SDK credentials implementations which support interacting with Posit OAuth integrations on Connect.
+"""Snowflake SDK integration.
 
-NOTE: The APIs in this module are provided as a convenience and are subject to breaking changes.
+Snowflake SDK credentials implementations which support interacting with Posit OAuth integrations on Connect.
+
+Notes
+-----
+The APIs in this module are provided as a convenience and are subject to breaking changes.
 """
 
 from typing_extensions import Optional

src/posit/connect/jobs.py

@@ -1,3 +1,5 @@
+"""Job resources."""
+
 from __future__ import annotations
 
 from typing_extensions import (

src/posit/connect/metrics/__init__.py

@@ -1 +1,3 @@
+"""Metric resources."""
+
 from .metrics import Metrics as Metrics