Azure / Azure/typespec-azure

Add linter rule to verify links in documentation

Open
#3,192 0 comments 0 reactions 0 assignees View on GitHub
design:needed lib:azure-core linter
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 21h
Merged PRs (30d)
164

Description

### Clear and concise description of the problem

We include the spec docs in generated library and the [CI pipelines verify the URLs](https://github.com/Azure/azure-sdk-for-java/blob/main/eng/common/scripts/Verify-Links.ps1#L412-L416) used in the library. So, any invalid links in the spec will result in failing the library build.

We should do this link verification in the spec validation phase to detect invalid links early in the process.

For example, [this spec](https://github.com/Azure/azure-rest-api-specs/blob/ef3298cf2eddaff616e393a7e5fd69bc380a8bd0/specification/orbital/Microsoft.PlanetaryComputer/sas.tsp#L83) contains a link with `/en-us/` locale and fails the link validation for generated libraries.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that this issue is about the Azure libraries for typespec. For feature request in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [x] Read the [docs](https://azure.github.io/typespec-azure/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked Verify-Links.ps1 checks and the example spec file specification/orbital/Microsoft.PlanetaryComputer/sas.tsp around line 83. Then locate the TypeScript spec validation entry point and determine how link failures should be reported; done means invalid documentation links are detected during spec validation rather than only during library builds.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell, typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.