Skip to content

Commit

Permalink
docs: remove headings from method doc (#30965)
Browse files Browse the repository at this point in the history
### Issue # (if applicable)

The documentation for [Stack#exportValue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options) contains an “Example” section formatted as an H2 with two H3 sub-sections, whereas the method signature uses an H3.

When generating documentation for CDK libraries inheriting from Stack, and jsii duplicates this “Example” section for each stack in the application in the API.md, this formatting issue causes a disruption in the heading hierarchy. This is particularly problematic on constructs.dev, where H3 headings are listed in the sidebar. Examples can be seen at:
- https://constructs.dev/packages/@condensetech/cdk-constructs/v/0.1.2?lang=typescript
- https://constructs.dev/packages/@cloudcomponents/cdk-temp-stack/v/2.4.0?lang=typescript
- https://constructs.dev/packages/@gammarers/aws-lambda-function-invoke-error-notification-stack/v/1.0.49?lang=typescript

### Reason for this change

By removing any heading from the method doc, there's no risk of altering the generated markdown hierarchy

### Description of changes

I've removed the headings from the method documentation

### Description of how you validated changes

N/A

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
nicolaracco authored Jul 31, 2024
1 parent a737e40 commit d367267
Showing 1 changed file with 2 additions and 4 deletions.
6 changes: 2 additions & 4 deletions packages/aws-cdk-lib/core/lib/stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1171,8 +1171,6 @@ export class Stack extends Construct implements ITaggable {
* remove the reference from the consuming stack. After that, you can remove
* the resource and the manual export.
*
* ## Example
*
* Here is how the process works. Let's say there are two stacks,
* `producerStack` and `consumerStack`, and `producerStack` has a bucket
* called `bucket`, which is referenced by `consumerStack` (perhaps because
Expand All @@ -1183,7 +1181,7 @@ export class Stack extends Construct implements ITaggable {
*
* Instead, the process takes two deployments:
*
* ### Deployment 1: break the relationship
* **Deployment 1: break the relationship**:
*
* - Make sure `consumerStack` no longer references `bucket.bucketName` (maybe the consumer
* stack now uses its own bucket, or it writes to an AWS DynamoDB table, or maybe you just
Expand All @@ -1193,7 +1191,7 @@ export class Stack extends Construct implements ITaggable {
* between the two stacks is being broken.
* - Deploy (this will effectively only change the `consumerStack`, but it's safe to deploy both).
*
* ### Deployment 2: remove the bucket resource
* **Deployment 2: remove the bucket resource**:
*
* - You are now free to remove the `bucket` resource from `producerStack`.
* - Don't forget to remove the `exportValue()` call as well.
Expand Down

0 comments on commit d367267

Please sign in to comment.