docs: added script to shorten documentation links Fixes #6195

[vjgaur]

Description

Added a script to automatically shorten documentation links and apply it to improve readability of the Polkadot SDK documentation. The script converts long-form documentation links to a shorter format while maintaining the full references at the bottom of each file.

Fixes #6195

Integration

The script is added to substrate/.maintain/ and can be used as follows:

Preview changes:

python3 substrate/.maintain/link-shortener.py --dry-run

Apply changes:

python3 substrate/.maintain/link-shortener.py

// Before:
[crate::reference_docs::blockchain_state_machines]

// After:
blockchain_state_machines

Review Notes

Detailed Implementation Overview

Approach

The script uses a systematic approach to transform documentation links:

1. File Processing

   • Recursively finds all .rs files in docs/sdk/src
   • Checks each file for presence of crate:: to optimize processing
   • Only modifies files that contain documentation links

2. Link Pattern Recognition
   PATTERNS = [ r'\[crate::reference_docs::[^]+\]', r'\[crate::polkadot_sdk::[^]`

These patterns target specific documentation sections while avoiding false positives.
3. Link Transformation Process
def replacer(match): # Extract full path: [crate::reference_docs::item] full_path = match.group(0) # Remove brackets: crate::reference_docs::item path_without_brackets = full_path[2:-2] # Get item name: item short_name = path_without_brackets.split("::")[-1] # Create new format return f'[{short_name}]({path_without_brackets})'

4. Reference Management
   Collects all unique references during processing
   Sorts references alphabetically
   Appends them at the end of the file in a dedicated section
   Maintains original paths for documentation linking

5. Safety Features
   Dry Run Mode: --dry-run flag shows changes without applying them
   Error Handling: Gracefully handles file reading/writing errors
   Progress Reporting: Shows which files are being processed
   Statistics: Reports number of files processed and modified

6. Testing
   The script can be tested in multiple ways.
   Dry run on all docs:
   python3 substrate/.maintain/link-shortener.py --dry-run

Test specific directory:
python3 substrate/.maintain/link-shortener.py --path docs/sdk/src/guides --dry-run

Results from Testing

Total files processed: 57
Files modified: 22
Common patterns found and transformed correctly
All references maintained and properly linked
Documentation functionality preserved while improving readability

Implementation details:

Script identifies documentation links using regex patterns
Processes .rs files in docs/sdk/src by default
Maintains all original references while improving readability
Includes dry-run mode for safe testing
Files processed: 57
Files modified: 22
No TODOs remaining.

Checklist

My PR includes a detailed description as outlined in the "Description" and its two subsections above.
My PR follows the labelling requirements (awaiting maintainer labels)
I have made corresponding changes to the documentation (this PR is documentation related)
I have added tests (script includes --dry-run option for testing)

Polkadot Address 👍

polkadot address: 14anwfyV1RYtHZjirHpfjAGaSQTirpYagGi8JaXCyy8fr3So

[kianenigma]

Suggested change

	//! [`async_backing_guide#timing-by-block-number`](crate::guides::async_backing_guide#timing-by-block-number).
	//! [`async_backing_guide#timing-by-block-number`].

I think for these final display should be like this, not containing the header.

[vjgaur]

Thanks for your suggestion.
I have incorporated those changes.
Let me know if thats fine

[kianenigma]

Suggested change

	//! Once done, feel free to step up into one of our templates: [`templates`](crate::polkadot_sdk::templates).
	//! Once done, feel free to step up into one of our templates: [`templates`](crate::polkadot_sdk::templates).

Suggested change

	//! Once done, feel free to step up into one of our templates: [`templates`](crate::polkadot_sdk::templates).
	//! Once done, feel free to step up into one of our templates: [`templates`].

So in all of them, you should now be able to remove the part that is inside the ().

[vjgaur]

@kianenigma
Thanks for your suggestion.
I have incorporated these changes.
Let me know if thats fine or anything else needs to be changed further

[vjgaur]

Hi @kianenigma I am trying to get through pr checks for prdoc
I am not sure what should go in crates because this script isn't impacting any crates but the documentation only. Initially I added substrate since it was giving me error later removed it than it asks for crates to be added , Kindly suggest what crates to be added in prdoc
Required { path: "/crates", },

[kianenigma]

with the label I have added, it should be good.

[vjgaur]

Thanks @kianenigma

[kianenigma]

Looks neat overall! I've spotted two small issues in the first few ones, will do a final review once they are also fixed.

Please provide your polkadot address for a tip.

[kianenigma]

Suggested change

//! Link References

And this line doesn't have to be here, because what comes after is not rendered.

[vjgaur]

Done fixed it.