From 9f7f4bdb8f7cd0f232937a7fa09f598fd94feecd Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Tue, 19 Dec 2023 17:17:05 +0000 Subject: [PATCH] fix: using split-by-submodule omits documentation for anything in the root of the project Extend the "index" page to contain a list of submodules and the reference for any symbols in the root namespace. --- src/docgen/render/markdown-render.ts | 2 + src/docgen/view/documentation.ts | 32 +- test/__snapshots__/cli.test.ts.snap | 1076 +++++++++++++++++++++++++- test/cli.test.ts | 5 + 4 files changed, 1111 insertions(+), 4 deletions(-) diff --git a/src/docgen/render/markdown-render.ts b/src/docgen/render/markdown-render.ts index e560a184..a0ff31e7 100644 --- a/src/docgen/render/markdown-render.ts +++ b/src/docgen/render/markdown-render.ts @@ -149,9 +149,11 @@ export class MarkdownRenderer { public visitSubmodules(submodules: readonly reflect.Submodule[], fileSuffix: string): MarkdownDocument { const md = new MarkdownDocument({ header: { title: 'Submodules' }, id: 'submodules' }); md.lines('The following submodules are available:'); + md.lines(''); for (const submodule of submodules) { md.lines(`- [${submoduleRelName(submodule)}](./${submoduleRelName(submodule)}.${fileSuffix})`); } + md.lines(''); return md; } diff --git a/src/docgen/view/documentation.ts b/src/docgen/view/documentation.ts index d5bc916a..5942b2cc 100644 --- a/src/docgen/view/documentation.ts +++ b/src/docgen/view/documentation.ts @@ -206,12 +206,40 @@ export class Documentation { public async toIndexMarkdown(fileSuffix:string, options: RenderOptions) { const assembly = await this.createAssembly(undefined, { loose: true, validate: false }); - - return MarkdownRenderer.fromSubmodules(await this.listSubmodules(), fileSuffix, { + const submodules = await this.listSubmodules(); + const schema = (await this.toJson({ ...options, + submodule: undefined, + allSubmodules: false, + })).content; + + const ref = new MarkdownDocument({ header: { title: 'API Reference' }, id: 'api-reference' }); + + if (schema.version !== CURRENT_SCHEMA_VERSION) { + throw new Error(`Unexpected schema version: ${schema.version}`); + } + + const renderer = new MarkdownRenderer({ + language: options.language, packageName: assembly.name, packageVersion: assembly.version, }); + + if (submodules.length) { + ref.section(renderer.visitSubmodules(submodules, fileSuffix)); + } + + if (schema.apiReference) { + ref.section(renderer.visitConstructs(schema.apiReference.constructs)); + ref.section(renderer.visitStructs(schema.apiReference.structs)); + ref.section(renderer.visitClasses(schema.apiReference.classes)); + ref.section(renderer.visitInterfaces(schema.apiReference.interfaces)); + ref.section(renderer.visitEnums(schema.apiReference.enums)); + } + + const documentation = new MarkdownDocument(); + documentation.section(ref); + return documentation; } /** diff --git a/test/__snapshots__/cli.test.ts.snap b/test/__snapshots__/cli.test.ts.snap index 69865e97..476e2c37 100644 --- a/test/__snapshots__/cli.test.ts.snap +++ b/test/__snapshots__/cli.test.ts.snap @@ -8389,10 +8389,1082 @@ first call to addToResourcePolicy(s). `; exports[`split-by-submodule creates submodule files next to output 1`] = ` -"# Submodules +"# API Reference + +## Submodules The following submodules are available: -- [submod1](./submod1.md)" + +- [submod1](./submod1.md) + +## Constructs + +### GreeterBucket + +#### Initializers + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +new GreeterBucket(scope: Construct, id: string, props?: BucketProps) +\`\`\` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | @aws-cdk/aws-s3.BucketProps | *No description.* | + +--- + +##### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +##### \`id\`Required + +- *Type:* string + +--- + +##### \`props\`Optional + +- *Type:* @aws-cdk/aws-s3.BucketProps + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| applyRemovalPolicy | Apply the given removal policy to this resource. | +| addEventNotification | Adds a bucket notification event destination. | +| addObjectCreatedNotification | Subscribes a destination to receive notifications when an object is created in the bucket. | +| addObjectRemovedNotification | Subscribes a destination to receive notifications when an object is removed from the bucket. | +| addToResourcePolicy | Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. | +| arnForObjects | Returns an ARN that represents all objects within the bucket that match the key pattern specified. | +| grantDelete | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. | +| grantPublicAccess | Allows unrestricted access to objects from this bucket. | +| grantPut | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. | +| grantPutAcl | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. | +| grantRead | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantReadWrite | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantWrite | Grant write permissions to this bucket to an IAM principal. | +| onCloudTrailEvent | Define a CloudWatch event that triggers when something happens to this repository. | +| onCloudTrailPutObject | Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. | +| onCloudTrailWriteObject | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. | +| s3UrlForObject | The S3 URL of an S3 object. For example:. | +| transferAccelerationUrlForObject | The https Transfer Acceleration URL of an S3 object. | +| urlForObject | The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. | +| virtualHostedUrlForObject | The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. | +| addCorsRule | Adds a cross-origin access configuration for objects in an Amazon S3 bucket. | +| addInventory | Add an inventory configuration. | +| addLifecycleRule | Add a lifecycle rule to the bucket. | +| addMetric | Adds a metrics configuration for the CloudWatch request metrics from the bucket. | +| greet | *No description.* | + +--- + +##### \`toString\` + +\`\`\`typescript +public toString(): string +\`\`\` + +Returns a string representation of this construct. + +##### \`applyRemovalPolicy\` + +\`\`\`typescript +public applyRemovalPolicy(policy: RemovalPolicy): void +\`\`\` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (\`RemovalPolicy.DESTROY\`), or left in your AWS +account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). + +###### \`policy\`Required + +- *Type:* @aws-cdk/core.RemovalPolicy + +--- + +##### \`addEventNotification\` + +\`\`\`typescript +public addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Adds a bucket notification event destination. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) + +*Example* + +\`\`\`typescript + declare const myLambda: lambda.Function; + const bucket = new s3.Bucket(this, 'MyBucket'); + bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'}); +\`\`\` + + +###### \`event\`Required + +- *Type:* @aws-cdk/aws-s3.EventType + +The event to trigger the notification. + +--- + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (Lambda, SNS Topic or SQS Queue). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +S3 object key filter rules to determine which objects trigger this event. + +Each filter must include a \`prefix\` and/or \`suffix\` +that will be matched against the s3 object key. Refer to the S3 Developer Guide +for details about allowed filter rules. + +--- + +##### \`addObjectCreatedNotification\` + +\`\`\`typescript +public addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is created in the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_CREATED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addObjectRemovedNotification\` + +\`\`\`typescript +public addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is removed from the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_REMOVED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addToResourcePolicy\` + +\`\`\`typescript +public addToResourcePolicy(permission: PolicyStatement): AddToResourcePolicyResult +\`\`\` + +Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. + +Note that the policy statement may or may not be added to the policy. +For example, when an \`IBucket\` is created from an existing bucket, +it's not possible to tell whether the bucket already has a policy +attached, let alone to re-use that policy to add more statements to it. +So it's safest to do nothing in these cases. + +###### \`permission\`Required + +- *Type:* @aws-cdk/aws-iam.PolicyStatement + +the policy statement to be added to the bucket's policy. + +--- + +##### \`arnForObjects\` + +\`\`\`typescript +public arnForObjects(keyPattern: string): string +\`\`\` + +Returns an ARN that represents all objects within the bucket that match the key pattern specified. + +To represent all keys, specify \`\`"*"\`\`. + +If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.: + + arnForObjects(\`home/\${team}/\${user}/*\`) + +###### \`keyPattern\`Required + +- *Type:* string + +--- + +##### \`grantDelete\` + +\`\`\`typescript +public grantDelete(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPublicAccess\` + +\`\`\`typescript +public grantPublicAccess(allowedActions: string, keyPrefix?: string): Grant +\`\`\` + +Allows unrestricted access to objects from this bucket. + +IMPORTANT: This permission allows anyone to perform actions on S3 objects +in this bucket, which is useful for when you configure your bucket as a +website and want everyone to be able to read objects in the bucket without +needing to authenticate. + +Without arguments, this method will grant read ("s3:GetObject") access to +all objects ("*") in the bucket. + +The method returns the \`iam.Grant\` object, which can then be modified +as needed. For example, you can add a condition that will restrict access only +to an IPv4 range like this: + + const grant = bucket.grantPublicAccess(); + grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” }); + +Note that if this \`IBucket\` refers to an existing bucket, possibly not +managed by CloudFormation, this method will have no effect, since it's +impossible to modify the policy of an existing bucket. + +###### \`allowedActions\`Required + +- *Type:* string + +the set of S3 actions to allow. + +Default is "s3:GetObject". + +--- + +###### \`keyPrefix\`Optional + +- *Type:* string + +the prefix of S3 object keys (e.g. \`home/*\`). Default is "*". + +--- + +##### \`grantPut\` + +\`\`\`typescript +public grantPut(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPutAcl\` + +\`\`\`typescript +public grantPutAcl(identity: IGrantable, objectsKeyPattern?: string): Grant +\`\`\` + +Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. + +If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, +calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; +in this case, if you need to modify object ACLs, call this method explicitly. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* string + +--- + +##### \`grantRead\` + +\`\`\`typescript +public grantRead(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If encryption is used, permission to use the key to decrypt the contents +of the bucket will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantReadWrite\` + +\`\`\`typescript +public grantReadWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If an encryption key is used, permission to use the key for +encrypt/decrypt will also be granted. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`grantWrite\` + +\`\`\`typescript +public grantWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant write permissions to this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`onCloudTrailEvent\` + +\`\`\`typescript +public onCloudTrailEvent(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Define a CloudWatch event that triggers when something happens to this repository. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailPutObject\` + +\`\`\`typescript +public onCloudTrailPutObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using \`onCloudTrailWriteObject\` may be preferable. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailWriteObject\` + +\`\`\`typescript +public onCloudTrailWriteObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. + +This includes +the events PutObject, CopyObject, and CompleteMultipartUpload. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using this method may be preferable to \`onCloudTrailPutObject\`. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`s3UrlForObject\` + +\`\`\`typescript +public s3UrlForObject(key?: string): string +\`\`\` + +The S3 URL of an S3 object. For example:. + +\`s3://onlybucket\` +- \`s3://bucket/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the S3 URL of the +bucket is returned. + +--- + +##### \`transferAccelerationUrlForObject\` + +\`\`\`typescript +public transferAccelerationUrlForObject(key?: string, options?: TransferAccelerationUrlOptions): string +\`\`\` + +The https Transfer Acceleration URL of an S3 object. + +Specify \`dualStack: true\` at the options +for dual-stack endpoint (connect to the bucket over IPv6). For example: + +- \`https://bucket.s3-accelerate.amazonaws.com\` +- \`https://bucket.s3-accelerate.amazonaws.com/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.TransferAccelerationUrlOptions + +Options for generating URL. + +--- + +##### \`urlForObject\` + +\`\`\`typescript +public urlForObject(key?: string): string +\`\`\` + +The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. + +\`https://s3.us-west-1.amazonaws.com/onlybucket\` +- \`https://s3.us-west-1.amazonaws.com/bucket/key\` +- \`https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +##### \`virtualHostedUrlForObject\` + +\`\`\`typescript +public virtualHostedUrlForObject(key?: string, options?: VirtualHostedStyleUrlOptions): string +\`\`\` + +The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. + +\`https://only-bucket.s3.us-west-1.amazonaws.com\` +- \`https://bucket.s3.us-west-1.amazonaws.com/key\` +- \`https://bucket.s3.amazonaws.com/key\` +- \`https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.VirtualHostedStyleUrlOptions + +Options for generating URL. + +--- + +##### \`addCorsRule\` + +\`\`\`typescript +public addCorsRule(rule: CorsRule): void +\`\`\` + +Adds a cross-origin access configuration for objects in an Amazon S3 bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.CorsRule + +The CORS configuration rule to add. + +--- + +##### \`addInventory\` + +\`\`\`typescript +public addInventory(inventory: Inventory): void +\`\`\` + +Add an inventory configuration. + +###### \`inventory\`Required + +- *Type:* @aws-cdk/aws-s3.Inventory + +configuration to add. + +--- + +##### \`addLifecycleRule\` + +\`\`\`typescript +public addLifecycleRule(rule: LifecycleRule): void +\`\`\` + +Add a lifecycle rule to the bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.LifecycleRule + +The rule to add. + +--- + +##### \`addMetric\` + +\`\`\`typescript +public addMetric(metric: BucketMetrics): void +\`\`\` + +Adds a metrics configuration for the CloudWatch request metrics from the bucket. + +###### \`metric\`Required + +- *Type:* @aws-cdk/aws-s3.BucketMetrics + +The metric configuration to add. + +--- + +##### \`greet\` + +\`\`\`typescript +public greet(): void +\`\`\` + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Return whether the given object is a Construct. | +| isResource | Check whether the given construct is a Resource. | +| fromBucketArn | *No description.* | +| fromBucketAttributes | Creates a Bucket construct that represents an external bucket. | +| fromBucketName | *No description.* | +| validateBucketName | Thrown an exception if the given bucket name is not valid. | + +--- + +##### \`isConstruct\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.isConstruct(x: any) +\`\`\` + +Return whether the given object is a Construct. + +###### \`x\`Required + +- *Type:* any + +--- + +##### \`isResource\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.isResource(construct: IConstruct) +\`\`\` + +Check whether the given construct is a Resource. + +###### \`construct\`Required + +- *Type:* @aws-cdk/core.IConstruct + +--- + +##### \`fromBucketArn\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketArn(scope: Construct, id: string, bucketArn: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketArn\`Required + +- *Type:* string + +--- + +##### \`fromBucketAttributes\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes) +\`\`\` + +Creates a Bucket construct that represents an external bucket. + +###### \`scope\`Required + +- *Type:* constructs.Construct + +The parent creating construct (usually \`this\`). + +--- + +###### \`id\`Required + +- *Type:* string + +The construct's name. + +--- + +###### \`attrs\`Required + +- *Type:* @aws-cdk/aws-s3.BucketAttributes + +A \`BucketAttributes\` object. + +Can be obtained from a call to +\`bucket.export()\` or manually created. + +--- + +##### \`fromBucketName\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketName(scope: Construct, id: string, bucketName: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketName\`Required + +- *Type:* string + +--- + +##### \`validateBucketName\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.validateBucketName(physicalName: string) +\`\`\` + +Thrown an exception if the given bucket name is not valid. + +###### \`physicalName\`Required + +- *Type:* string + +name of the bucket. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | @aws-cdk/core.ConstructNode | The construct tree node associated with this construct. | +| env | @aws-cdk/core.ResourceEnvironment | The environment this resource belongs to. | +| stack | @aws-cdk/core.Stack | The stack in which this resource is defined. | +| bucketArn | string | The ARN of the bucket. | +| bucketDomainName | string | The IPv4 DNS name of the specified bucket. | +| bucketDualStackDomainName | string | The IPv6 DNS name of the specified bucket. | +| bucketName | string | The name of the bucket. | +| bucketRegionalDomainName | string | The regional domain name of the specified bucket. | +| bucketWebsiteDomainName | string | The Domain name of the static website. | +| bucketWebsiteUrl | string | The URL of the static website. | +| encryptionKey | @aws-cdk/aws-kms.IKey | Optional KMS encryption key associated with this bucket. | +| isWebsite | boolean | If this bucket has been configured for static website hosting. | +| policy | @aws-cdk/aws-s3.BucketPolicy | The resource policy associated with this bucket. | + +--- + +##### \`node\`Required + +\`\`\`typescript +public readonly node: ConstructNode; +\`\`\` + +- *Type:* @aws-cdk/core.ConstructNode + +The construct tree node associated with this construct. + +--- + +##### \`env\`Required + +\`\`\`typescript +public readonly env: ResourceEnvironment; +\`\`\` + +- *Type:* @aws-cdk/core.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### \`stack\`Required + +\`\`\`typescript +public readonly stack: Stack; +\`\`\` + +- *Type:* @aws-cdk/core.Stack + +The stack in which this resource is defined. + +--- + +##### \`bucketArn\`Required + +\`\`\`typescript +public readonly bucketArn: string; +\`\`\` + +- *Type:* string + +The ARN of the bucket. + +--- + +##### \`bucketDomainName\`Required + +\`\`\`typescript +public readonly bucketDomainName: string; +\`\`\` + +- *Type:* string + +The IPv4 DNS name of the specified bucket. + +--- + +##### \`bucketDualStackDomainName\`Required + +\`\`\`typescript +public readonly bucketDualStackDomainName: string; +\`\`\` + +- *Type:* string + +The IPv6 DNS name of the specified bucket. + +--- + +##### \`bucketName\`Required + +\`\`\`typescript +public readonly bucketName: string; +\`\`\` + +- *Type:* string + +The name of the bucket. + +--- + +##### \`bucketRegionalDomainName\`Required + +\`\`\`typescript +public readonly bucketRegionalDomainName: string; +\`\`\` + +- *Type:* string + +The regional domain name of the specified bucket. + +--- + +##### \`bucketWebsiteDomainName\`Required + +\`\`\`typescript +public readonly bucketWebsiteDomainName: string; +\`\`\` + +- *Type:* string + +The Domain name of the static website. + +--- + +##### \`bucketWebsiteUrl\`Required + +\`\`\`typescript +public readonly bucketWebsiteUrl: string; +\`\`\` + +- *Type:* string + +The URL of the static website. + +--- + +##### \`encryptionKey\`Optional + +\`\`\`typescript +public readonly encryptionKey: IKey; +\`\`\` + +- *Type:* @aws-cdk/aws-kms.IKey + +Optional KMS encryption key associated with this bucket. + +--- + +##### \`isWebsite\`Optional + +\`\`\`typescript +public readonly isWebsite: boolean; +\`\`\` + +- *Type:* boolean + +If this bucket has been configured for static website hosting. + +--- + +##### \`policy\`Optional + +\`\`\`typescript +public readonly policy: BucketPolicy; +\`\`\` + +- *Type:* @aws-cdk/aws-s3.BucketPolicy + +The resource policy associated with this bucket. + +If \`autoCreatePolicy\` is true, a \`BucketPolicy\` will be created upon the +first call to addToResourcePolicy(s). + +--- + + + + + +" `; exports[`split-by-submodule creates submodule files next to output 2`] = ` diff --git a/test/cli.test.ts b/test/cli.test.ts index 05a9e41f..2edd5000 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -68,6 +68,11 @@ test('split-by-submodule creates submodule files next to output', () => { const rootMd = readFileSync(join(fixture, 'docs/API.md'), 'utf-8'); const submoduleMd = readFileSync(join(fixture, 'docs/submod1.md'), 'utf-8'); expect(rootMd).toMatchSnapshot(); + expect(rootMd).toContain('# API Reference'); + expect(rootMd).toContain('## Submodules'); + expect(rootMd).toContain('- [submod1](./submod1.md)'); + expect(rootMd).toContain('## Constructs'); + expect(rootMd).toContain('GreeterBucket'); expect(submoduleMd).toMatchSnapshot(); }); \ No newline at end of file