docs improvements

Author: cfeenstra67

packages/aws/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @stackattack/aws
 
+## 0.6.0
+
+### Minor Changes
+
+- Add azs argument to vpc.network
+
+### Patch Changes
+
+- Remove unused publicSubnetIds arg from vpn, export vpn interfaces
+- Add default tags to context
+
 ## 0.5.1
 
 ### Patch Changes

packages/aws/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackattack/aws",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "High-level, production-ready AWS components for Pulumi",
   "homepage": "https://stackattack.camfeenstra.com",
   "repository": "github:cfeenstra67/stackattack",

packages/aws/src/components/vpn.ts

@@ -8,9 +8,15 @@
  *
  * const ctx = saws.context();
  * const vpc = saws.vpc(ctx);
- * const vpnEndpoint = saws.vpn(ctx, vpc);
+ * const vpn = saws.vpn(ctx, vpc);
  *
- * export const vpnClientConfig = vpnEndpoint.clientConfig;
+ * // If you'd only like to associate the VPN with a single subnet (cheapest option)
+ * // const vpn = saws.vpn(ctx, {
+ * //   ...vpc,
+ * //   privateSubnetIds: vpc.privateSubnetIds.slice(0, 1)
+ * // })
+ *
+ * export const vpnClientConfig = vpn.clientConfig;
  * ```
  *
  * ## Usage
@@ -39,7 +45,7 @@
  *
  * Cost optimization strategies:
  * - Use split tunneling (enabled by default) to avoid routing all traffic through AWS.
- * - AWS [recommends](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AssociateClientVpnTargetNetwork.html) associating your client VPN endpoint with at least two subnets for availability, but you can associate a single subnet if you'd prefer. You are charged per subnet association per hour, so the number of subnets the VPN is associated with highly correlated with the cost.
+ * - AWS [recommends](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AssociateClientVpnTargetNetwork.html) associating your client VPN endpoint with at least two subnets for availability, but you can associate a single subnet if you'd prefer (see example above). You are charged per subnet association per hour, so the number of subnets the VPN is associated with highly correlated with the cost.
  *
  * See the [AWS VPN Pricing](https://aws.amazon.com/vpn/pricing/) for current rates.
  *
@@ -139,7 +145,7 @@ export function vpnCertificate(
 /**
  * Configuration for generating OpenVPN client configuration file.
  */
-interface GenerateClientConfigArgs {
+export interface ClientConfigFileArgs {
   /** Name used for the client configuration */
   name: pulumi.Input<string>;
   /** VPN server hostname (may contain wildcards) */
@@ -165,7 +171,7 @@ export function clientConfigFile({
   certificateChain,
   clientCertificate,
   clientPrivateKey,
-}: GenerateClientConfigArgs): pulumi.Output<string> {
+}: ClientConfigFileArgs): pulumi.Output<string> {
   const remote = pulumi
     .all([hostname, name])
     .apply(([h, name]) => h.replace("*", name));
@@ -200,13 +206,11 @@ verify-x509-name server name`;
 /**
  * Configuration options for creating an AWS Client VPN endpoint.
  */
-interface VpnArgs {
+export interface VpnArgs {
   /** VPC where the VPN endpoint will be created */
   vpc: pulumi.Input<VpcInput>;
   /** Private subnet IDs for VPN network associations */
   privateSubnetIds: pulumi.Input<string>[];
-  /** Public subnet IDs (currently unused but part of interface) */
-  publicSubnetIds: pulumi.Input<string>[];
   /** Pre-generated VPN certificates, will auto-generate if not provided */
   certificate?: pulumi.Input<VPNCertificateOutput>;
   /** Security group IDs to attach to the VPN endpoint */

packages/docs/generate.ts

@@ -5,6 +5,7 @@ import {
   DeclarationReflection,
   ParameterReflection,
   ReflectionKind,
+  SignatureReflection,
 } from "typedoc";
 
 // Helper function to format TypeDoc comments
@@ -51,6 +52,32 @@ function formatParameters(
   return result;
 }
 
+function formatReturnType(
+  signature: SignatureReflection | undefined,
+  typeMap: Map<string, { componentName: string; anchor: string }>,
+  isUtility = false,
+  hasMainFunction = true,
+): string {
+  if (!signature?.type) return "";
+
+  const headingLevel = isUtility || !hasMainFunction ? "###" : "####";
+
+  let result = `\n${headingLevel} Returns\n\n`;
+  const typeStr = signature.type.toString();
+
+  const linkedType = formatTypeWithLinks(typeStr, typeMap);
+  const description = formatComment(signature.comment);
+
+  const formattedType = formatTypeAsCode(linkedType);
+  const cleanedType = formattedType
+    .replace(/`\s+\[/g, "`[")
+    .replace(/\]\s+`/g, "]`");
+
+  result += `- (${cleanedType}) - ${description}\n`;
+
+  return result;
+}
+
 // Helper function to convert types to links where possible
 function formatTypeWithLinks(
   typeStr: string,
@@ -67,9 +94,6 @@ function formatTypeWithLinks(
     );
   }
 
-  // Handle Context type (from context.ts, not in components)
-  result = result.replace(/\bContext\b/g, "`[Context](/concepts/context/)`");
-
   return result;
 }
 
@@ -258,6 +282,7 @@ sourceUrl: https://github.com/cfeenstra67/stackattack/blob/main/packages/aws/src
       isUtility,
       true,
     )}\n`;
+    markdown += formatReturnType(mainFunction.signatures?.[0], typeMap);
   }
 
   // Group remaining declarations by type
@@ -444,15 +469,41 @@ async function generateDocs() {
           });
         }
 
+        const children = child.children?.sort((a, b) => {
+          let aType = false;
+          if (
+            a.kind === ReflectionKind.Interface ||
+            a.kind === ReflectionKind.TypeAlias
+          ) {
+            aType = true;
+          }
+          let bType = false;
+          if (
+            b.kind === ReflectionKind.Interface ||
+            b.kind === ReflectionKind.TypeAlias
+          ) {
+            bType = true;
+          }
+          if (aType === bType) {
+            return 0;
+          }
+          return aType ? 1 : -1;
+        });
+
         // If this is a module, get its children (the actual exports)
-        if (child.kind === ReflectionKind.Module && child.children) {
+        if (child.kind === ReflectionKind.Module && children) {
           // Store the module itself for potential @packageDocumentation comment
           const moduleDecl = child as DeclarationReflection;
           targetMap.get(targetName)!.declarations.push(moduleDecl);
 
-          for (const decl of child.children) {
+          const anchorCounts: Record<string, number> = {};
+          for (const decl of children) {
             targetMap.get(targetName)!.declarations.push(decl);
 
+            const anchor = decl.name.toLowerCase();
+            anchorCounts[anchor] ??= -1;
+            anchorCounts[anchor]++;
+
             // Add to type map for cross-linking
             if (
               decl.kind === ReflectionKind.Interface ||
@@ -464,9 +515,13 @@ async function generateDocs() {
                   : type === "concept"
                     ? `/concepts/${targetName}/`
                     : `/components/${targetName}/`;
+
+              const ct = anchorCounts[anchor];
+              const fullAnchor = ct === 0 ? anchor : `${anchor}-${ct}`;
+
               typeMap.set(decl.name, {
                 componentName: linkPath,
-                anchor: `#${decl.name.toLowerCase()}`,
+                anchor: `#${fullAnchor}`,
               });
             }
           }

packages/docs/package.json

@@ -10,7 +10,7 @@
     "build-only": "astro build",
     "build": "pnpm generate && pnpm build-only",
     "preview": "astro preview",
-    "generate": "rm -r src/content/docs/{components,utilities,components.md} || true && tsx generate.ts",
+    "generate": "rm -r src/content/docs/{components,utilities,concepts,components.md} || true && tsx generate.ts",
     "check": "biome check --apply src *.ts"
   },
   "keywords": [],