[Website] Inject source links into generated legacy JS API docs
- Dominant language
- HTML
- Stars
- 40
- Forks
- 133
- Avg merge
- 1h 3m
- Merged PRs (30d)
- 8
Description
Following up from https://github.com/apache/arrow-js/issues/180
### Rationale
Starting from version 17.0.0 the generated TypeDoc API docs no longer link any "Defined in ..." references to their GitHub source. Additionally, arrow-js has since been moved out of the monorepo but didn't migrate any version tags, making it more challenging for developers to find the sources for older versions.
[npm stats show](https://www.npmjs.com/package/apache-arrow?activeTab=versions) that versions before 20.0.0 still see widespread use (e.g., duckdb-wasm 1.29.0 references apache-arrow 17.0.0).
### Suggested solution
All of the affected lines in the markup follow a consistent pattern. We can therefore simply inject the links into the [already generated markup](https://github.com/apache/arrow-site/tree/asf-site/docs) instead of having to fix the TypeDoc configuration and rebuilding the docs.
Example:
```diff
-
+
```
Shell script to apply the changes:
```sh
add-source-links()
{
local docs_path="$1"
local base_url="$2"
find "$docs_path" \
-name '*.html' \
-exec sed -Ei '' 's'';
}
add-source-links docs/17.0/js 'https://github.com/apache/arrow/tree/apache-arrow-17.0.0/js/src/'
add-source-links docs/18.0/js 'https://github.com/apache/arrow/tree/apache-arrow-18.0.0/js/src/'
add-source-links docs/18.1/js 'https://github.com/apache/arrow/tree/apache-arrow-18.1.0/js/src/'
add-source-links docs/19.0/js 'https://github.com/apache/arrow/tree/apache-arrow-19.0.0/js/src/'
add-source-links docs/js 'https://github.com/apache/arrow/tree/apache-arrow-20.0.0/js/src/'
```
Note that `-exec sed -Ei '' 's…` is macOS specific and may need to be changed to `-exec sed -Ei 's…` on other systems.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the generated markup under docs/17.0/js, docs/18.0/js, docs/18.1/js, docs/19.0/js, and docs/js, then review the add-source-links shell function and its version-specific base URLs. Apply the consistent Defined in link transformation and verify that the affected HTML references point to the matching GitHub source tags and line numbers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100