Link API docs to source files

[mootari]

Describe the enhancement requested

The TypeDoc generated API docs currently list the source location of a file as for example

Defined in visitor.ts:21
Defined in visitor.ts:223

It would be helpful to have these link straight to the source for the ref from which the docs were generated.

[amoeba]

Thanks for the issue @mootari, this seems like a good improvement. Would you be interested in opening a PR?

[mootari]

@amoeba I started looking into it but the recent migration complicates things:

1. The workflow builds the docs for the version defined in package.json (currently 21.0.0), and it's not clear to me where they are currently made available.
2. None of the former tags have been migrated, so it's currently not possible to target version 20.0.0.

If I may, I'd suggest to migrate at least the major version tags to this repo so that

• users don't have to be gated to the old repo based on which version they're trying to look up the sources for
• TypeDoc's git integration can be utilized (instead of specfying a sourceLinkTemplate)
• there's a better chance of being able to serve multiple version docs simultaneously (per Add version switcher to documentation #170 - duckdb-wasm 1.29.0 e.g. still pulls in 17.0.0)

[kou]

It seems that the current build results have links: https://arrow.apache.org/js/main/classes/Arrow.dom.Visitor.html

[amoeba]

Thanks @kou. Do you know why we're publishing the dev docs at that URL and not as part of the docs site (specifically docs/dev)?

@mootari is it possible the issue is fixed in the latest dev build of the docs?

[mootari]

@amoeba It seems fixed for the latest dev build, but would remain an issue for any prior versions. I don't mind merging that as a requirement into #170 though once the dev docs are publicly linked.

[amoeba]

Backporting the fix to older versions would be done as a PR to the asf-site branch on the https://github.com/apache/arrow-site/ repo (old docs for each version are stored under docs/$VERSION/js) and looks like it'd involve a substantial amount of work. I think I'd be in favor of just making sure the latest and future versions have working links. What do you think?

[mootari]

Hmm... If those docs never get regenerated then we might just get away with a simple search/replace in the generated HTML.

Simple example:

`<aside class="tsd-sources"><ul><li>Defined in row/struct.ts:34</li></ul></aside>`.replace(
  /<li>Defined in (([^:]+):(\d+))<\/li>/g,
  `<li>Defined in <a href="https://github.com/apache/arrow/tree/apache-arrow-19.0.1/js/src/$2#L$3">$1</li>`
)

Alternatively it could be applied as a patch after TypeDoc ran. All the script would need is the base path for the respective version.

[amoeba]

That might work. Can we either update this ticket to reflect the new direction or file a new issue?

Also, Re:

Thanks @kou. Do you know why we're publishing the dev docs at that URL and not as part of the docs site (specifically docs/dev)?

I just realized this is the URL structure we're using for other projects we separated from the monorepo.

[kou]

Yes.

In general, we use https://arrow.apache.org/${XXX}/... for apache/arrow-XXX repositories. If we use https://arrow.apache.org/{,${VERSION}/}docs/js/..., we need to update apache/arrow-site. If we use https://arrow.apache.org/${XXX}/..., we can keep using apache/arrow-XXX.

FYI: Here is the .asf.yaml configuration for this:

arrow-js/.asf.yaml

Lines 44 to 46 in aff7891

	publish:
	whoami: asf-site
	subdir: js

[amoeba]

Nice, thanks.

[mootari]

Given the expected size of the PR for the legacy docs, should I file a separate issue in arrow-site first to describe the motivation and planned approach, or is it sufficient to just include that in the PR description?

Edit: only affects

• docs/17.0/js
• docs/18.0/js
• docs/18.1/js
• docs/19.0/js
• docs/dev/js (probably not relevant anymore?)
• docs/js (which I think needs to be renamed to docs/20.0/js?)

[kou]

Could you open one issue in https://github.com/apache/arrow-site ?
We can use one PR for this. It will be a large PR as you mentioned but it's still large PRs even if we separate it to each version. We can't review them by eye. We need to write a simple script to validate it.

• docs/dev/js (probably not relevant anymore?)

Right. We should remove it and redirect https://arrow.apache.org/docs/dev/js/ to https://arrow.apache.org/js/main/ . But it's out of scope of this issue.

docs/js (which I think needs to be renamed to docs/20.0/js?)

We need to update it too but we don't need to rename it. Because renaming will be done automatically in the apache/arrow 21.0.0 release process.

[mootari]

It will be a large PR as you mentioned but it's still large PRs even if we separate it to each version.

The list was only meant to point out the affected versions, not to suggest that we create separate issues or PRs for each.