apache / apache/arrow-site

[Website] Inject source links into generated legacy JS API docs

Open
#664 2 comments 0 reactions 0 assignees View on GitHub
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
-

  • Defined in builder.ts:102

  • +
  • Defined in builder.ts:102builder.ts:102

  • ```

    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'';

  • Defined in (([^<]+):([0-9]+))
  • ;
  • Defined in \1
  • ;g' {} +
    }

    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

    Get new issues in your inbox

    A short digest of beginner-friendly GitHub issues.