feat: resource docs

codegen/pkg/builder/out.go

@@ -100,12 +100,13 @@ func (b *Builder) generateResourceIndex(tagName string, resourceTypes []string)
 }
 
 type resourceTemplateData struct {
-	PackageName string
-	TypeNames   []string
-	Params      []Writable
-	Service     string
-	Methods     []*Method
-	UsesSecret  bool
+	PackageName    string
+	TypeNames      []string
+	Params         []Writable
+	Service        string
+	Methods        []*Method
+	UsesSecret     bool
+	TagDescription string
 }
 
 func (b *Builder) generateResourceFile(tagName string, paths *v3.Paths) ([]string, error) {
@@ -139,12 +140,13 @@ func (b *Builder) generateResourceFile(tagName string, paths *v3.Paths) ([]strin
 
 	serviceBuf := bytes.NewBuffer(nil)
 	if err := b.templates.ExecuteTemplate(serviceBuf, "resource.py.tmpl", resourceTemplateData{
-		PackageName: strcase.ToSnake(tag.Name),
-		TypeNames:   typeNames,
-		Params:      innerTypes,
-		Service:     strcase.ToCamel(tag.Name),
-		Methods:     methods,
-		UsesSecret:  usesSecret,
+		PackageName:    strcase.ToSnake(tag.Name),
+		TypeNames:      typeNames,
+		Params:         innerTypes,
+		Service:        strcase.ToCamel(tag.Name),
+		Methods:        methods,
+		UsesSecret:     usesSecret,
+		TagDescription: strings.TrimSpace(tag.Description),
 	}); err != nil {
 		return nil, err
 	}
@@ -232,8 +234,9 @@ func (b *Builder) writeClientFile(fname string, tags []string) error {
 	}()
 
 	type resource struct {
-		Name    string
-		Package string
+		Name           string
+		Package        string
+		ShortDocstring string
 	}
 
 	resources := make([]resource, 0, len(tags))
@@ -242,8 +245,9 @@ func (b *Builder) writeClientFile(fname string, tags []string) error {
 			continue
 		}
 		resources = append(resources, resource{
-			Name:    strcase.ToCamel(tags[i]),
-			Package: strcase.ToSnake(tags[i]),
+			Name:           strcase.ToCamel(tags[i]),
+			Package:        strcase.ToSnake(tags[i]),
+			ShortDocstring: fmt.Sprintf("Access the %s API endpoints.", strcase.ToCamel(tags[i])),
 		})
 	}
 

codegen/templates/client.py.tmpl

@@ -43,6 +43,7 @@ class Sumup(Resource):
 {{- range .Resources }}
     @property
     def {{ .Package }}(self) -> {{ .Name }}Resource:
+        """{{ .ShortDocstring }}"""
         from .{{ .Package }}.resource import {{ .Name }}Resource
 
         return {{ .Name }}Resource(self._client)
@@ -71,6 +72,7 @@ class AsyncSumup(AsyncResource):
 {{- range .Resources }}
     @property
     def {{ .Package }}(self) -> Async{{ .Name }}Resource:
+        """{{ .ShortDocstring }}"""
         from .{{ .Package }}.resource import Async{{ .Name }}Resource
 
         return Async{{ .Name }}Resource(self._client)

codegen/templates/resource.py.tmpl

@@ -1,4 +1,9 @@
 # Code generated by `py-sdk-gen`. DO NOT EDIT.
+{{- with .TagDescription }}
+"""
+{{ . }}
+"""
+{{- end }}
 from __future__ import annotations
 from .._service import Resource, AsyncResource, HeaderTypes
 from .._exceptions import APIError
@@ -21,6 +26,8 @@ import typing_extensions
 
 
 class {{.Service}}Resource(Resource):
+	"""API resource for the {{.Service}} endpoints."""
+
 	def __init__(self, client: httpx.Client) -> None:
 		super().__init__(client)
 
@@ -69,6 +76,8 @@ class {{.Service}}Resource(Resource):
 {{end}}
 
 class Async{{.Service}}Resource(AsyncResource):
+	"""Async API resource for the {{.Service}} endpoints."""
+
 	def __init__(self, client: httpx.AsyncClient) -> None:
 		super().__init__(client)
 

sumup/_client.py

@@ -52,66 +52,77 @@ def __init__(
 
     @property
     def checkouts(self) -> CheckoutsResource:
+        """Access the Checkouts API endpoints."""
         from .checkouts.resource import CheckoutsResource
 
         return CheckoutsResource(self._client)
 
     @property
     def customers(self) -> CustomersResource:
+        """Access the Customers API endpoints."""
         from .customers.resource import CustomersResource
 
         return CustomersResource(self._client)
 
     @property
     def members(self) -> MembersResource:
+        """Access the Members API endpoints."""
         from .members.resource import MembersResource
 
         return MembersResource(self._client)
 
     @property
     def memberships(self) -> MembershipsResource:
+        """Access the Memberships API endpoints."""
         from .memberships.resource import MembershipsResource
 
         return MembershipsResource(self._client)
 
     @property
     def merchants(self) -> MerchantsResource:
+        """Access the Merchants API endpoints."""
         from .merchants.resource import MerchantsResource
 
         return MerchantsResource(self._client)
 
     @property
     def payouts(self) -> PayoutsResource:
+        """Access the Payouts API endpoints."""
         from .payouts.resource import PayoutsResource
 
         return PayoutsResource(self._client)
 
     @property
     def readers(self) -> ReadersResource:
+        """Access the Readers API endpoints."""
         from .readers.resource import ReadersResource
 
         return ReadersResource(self._client)
 
     @property
     def receipts(self) -> ReceiptsResource:
+        """Access the Receipts API endpoints."""
         from .receipts.resource import ReceiptsResource
 
         return ReceiptsResource(self._client)
 
     @property
     def roles(self) -> RolesResource:
+        """Access the Roles API endpoints."""
         from .roles.resource import RolesResource
 
         return RolesResource(self._client)
 
     @property
     def subaccounts(self) -> SubaccountsResource:
+        """Access the Subaccounts API endpoints."""
         from .subaccounts.resource import SubaccountsResource
 
         return SubaccountsResource(self._client)
 
     @property
     def transactions(self) -> TransactionsResource:
+        """Access the Transactions API endpoints."""
         from .transactions.resource import TransactionsResource
 
         return TransactionsResource(self._client)
@@ -140,66 +151,77 @@ def __init__(
 
     @property
     def checkouts(self) -> AsyncCheckoutsResource:
+        """Access the Checkouts API endpoints."""
         from .checkouts.resource import AsyncCheckoutsResource
 
         return AsyncCheckoutsResource(self._client)
 
     @property
     def customers(self) -> AsyncCustomersResource:
+        """Access the Customers API endpoints."""
         from .customers.resource import AsyncCustomersResource
 
         return AsyncCustomersResource(self._client)
 
     @property
     def members(self) -> AsyncMembersResource:
+        """Access the Members API endpoints."""
         from .members.resource import AsyncMembersResource
 
         return AsyncMembersResource(self._client)
 
     @property
     def memberships(self) -> AsyncMembershipsResource:
+        """Access the Memberships API endpoints."""
         from .memberships.resource import AsyncMembershipsResource
 
         return AsyncMembershipsResource(self._client)
 
     @property
     def merchants(self) -> AsyncMerchantsResource:
+        """Access the Merchants API endpoints."""
         from .merchants.resource import AsyncMerchantsResource
 
         return AsyncMerchantsResource(self._client)
 
     @property
     def payouts(self) -> AsyncPayoutsResource:
+        """Access the Payouts API endpoints."""
         from .payouts.resource import AsyncPayoutsResource
 
         return AsyncPayoutsResource(self._client)
 
     @property
     def readers(self) -> AsyncReadersResource:
+        """Access the Readers API endpoints."""
         from .readers.resource import AsyncReadersResource
 
         return AsyncReadersResource(self._client)
 
     @property
     def receipts(self) -> AsyncReceiptsResource:
+        """Access the Receipts API endpoints."""
         from .receipts.resource import AsyncReceiptsResource
 
         return AsyncReceiptsResource(self._client)
 
     @property
     def roles(self) -> AsyncRolesResource:
+        """Access the Roles API endpoints."""
         from .roles.resource import AsyncRolesResource
 
         return AsyncRolesResource(self._client)
 
     @property
     def subaccounts(self) -> AsyncSubaccountsResource:
+        """Access the Subaccounts API endpoints."""
         from .subaccounts.resource import AsyncSubaccountsResource
 
         return AsyncSubaccountsResource(self._client)
 
     @property
     def transactions(self) -> AsyncTransactionsResource:
+        """Access the Transactions API endpoints."""
         from .transactions.resource import AsyncTransactionsResource
 
         return AsyncTransactionsResource(self._client)

sumup/checkouts/resource.py

@@ -1,4 +1,12 @@
 # Code generated by `py-sdk-gen`. DO NOT EDIT.
+"""
+Accept payments from your end users by adding the Checkouts model to your platform.
+SumUp supports standard and single payment 3DS checkout flows.
+
+The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts.
+A payment is completed by creating a checkout and then processing the checkout.
+"""
+
 from __future__ import annotations
 from .._service import Resource, AsyncResource, HeaderTypes
 from .._exceptions import APIError
@@ -194,6 +202,8 @@ class GetPaymentMethods200Response(pydantic.BaseModel):
 
 
 class CheckoutsResource(Resource):
+    """API resource for the Checkouts endpoints."""
+
     def __init__(self, client: httpx.Client) -> None:
         super().__init__(client)
 
@@ -384,6 +394,8 @@ def deactivate(self, id: str, headers: typing.Optional[HeaderTypes] = None) -> C
 
 
 class AsyncCheckoutsResource(AsyncResource):
+    """Async API resource for the Checkouts endpoints."""
+
     def __init__(self, client: httpx.AsyncClient) -> None:
         super().__init__(client)
 

sumup/customers/resource.py

@@ -1,4 +1,11 @@
 # Code generated by `py-sdk-gen`. DO NOT EDIT.
+"""
+Allow your regular customers to save their information with the Customers model.
+This will prevent re-entering payment instrument information for recurring payments on your platform.
+
+Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.
+"""
+
 from __future__ import annotations
 from .._service import Resource, AsyncResource, HeaderTypes
 from .._exceptions import APIError
@@ -46,6 +53,8 @@ class UpdateCustomerBody(pydantic.BaseModel):
 
 
 class CustomersResource(Resource):
+    """API resource for the Customers endpoints."""
+
     def __init__(self, client: httpx.Client) -> None:
         super().__init__(client)
 
@@ -219,6 +228,8 @@ def deactivate_payment_instrument(
 
 
 class AsyncCustomersResource(AsyncResource):
+    """Async API resource for the Customers endpoints."""
+
     def __init__(self, client: httpx.AsyncClient) -> None:
         super().__init__(client)
 

sumup/members/resource.py

@@ -1,4 +1,8 @@
 # Code generated by `py-sdk-gen`. DO NOT EDIT.
+"""
+Endpoints to manage account members. Members are users that have membership within merchant accounts.
+"""
+
 from __future__ import annotations
 from .._service import Resource, AsyncResource, HeaderTypes
 from .._exceptions import APIError
@@ -139,6 +143,8 @@ class ListMerchantMembers200Response(pydantic.BaseModel):
 
 
 class MembersResource(Resource):
+    """API resource for the Members endpoints."""
+
     def __init__(self, client: httpx.Client) -> None:
         super().__init__(client)
 
@@ -278,6 +284,8 @@ def delete(
 
 
 class AsyncMembersResource(AsyncResource):
+    """Async API resource for the Members endpoints."""
+
     def __init__(self, client: httpx.AsyncClient) -> None:
         super().__init__(client)
 

sumup/memberships/resource.py

@@ -1,4 +1,8 @@
 # Code generated by `py-sdk-gen`. DO NOT EDIT.
+"""
+Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.
+"""
+
 from __future__ import annotations
 from .._service import Resource, AsyncResource, HeaderTypes
 from .._exceptions import APIError
@@ -92,6 +96,8 @@ class ListMemberships200Response(pydantic.BaseModel):
 
 
 class MembershipsResource(Resource):
+    """API resource for the Memberships endpoints."""
+
     def __init__(self, client: httpx.Client) -> None:
         super().__init__(client)
 
@@ -127,6 +133,8 @@ def list(
 
 
 class AsyncMembershipsResource(AsyncResource):
+    """Async API resource for the Memberships endpoints."""
+
     def __init__(self, client: httpx.AsyncClient) -> None:
         super().__init__(client)