aws / aws/aws-cdk

docs: source links for v2 point to files that don't exist in the source repository

Open
#17,903 3 comments 0 reactions 0 assignees View on GitHub
aws-cdk-lib bug effort/medium p1
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
1d 19h
Merged PRs (30d)
71

Description

### What is the problem?

![image](https://user-images.githubusercontent.com/524162/145186931-0d143d6f-aa98-4f14-acf9-9d29e5b12202.png)

> I noticed that all the TypeScript github source links in the docs are not going to the correct destination. Example: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codedeploy.EcsDeploymentGroup.html has https://github.com/aws/aws-cdk/blob/v2.0.0/packages/aws-cdk-lib/aws-codedeploy/lib/ecs/deployment-group.ts#L42.

### Cause

The reason is that these source files are generated at build time -- they never exist in the source repository, and hence cannot be linked to.

### Solution

We need to strip source locations of files that don't exist in the repository. This is complicated *slightly* by the fact that our build can run separately from a git clone, so we need to do the following:

* Before the build: generate a list of all source files in the current directory
* If git use `git ls-files`
* Otherwise use `find`
* After the build (before pack), modify all assemblies in place, stripping sourceLocations that aren't in the file list

Contributor guide

Open the contributing guide

Research direction

Trace the build steps that generate assemblies and run before pack; inspect how sourceLocations are produced and where the source-file list can be captured. Compare the list from git ls-files, or find when no Git clone is available, with the generated locations. Done means locations for files absent from the repository are stripped so the v2 documentation links no longer target nonexistent files.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, typescript
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.