Support for specifying the base file url in gitRemote

[Nclark89]

Search terms

Question

Hello, when navigating the typedoc examples I noticed it was possible to link the source code function

In this case: https://typedoc.org/example/functions/sqrt.html it links to https://github.com/TypeStrong/typedoc/blob/v0.23.15/example/src/functions.ts#L7

How is this achieved ? I've tried using https://github.com/gdelmas/typedoc-plugin-sourcefile-url but it doesn't seem to be compatible with the latest typedoc version and since the website supported it here https://typedoc.org/example/functions/sqrt.html I guess it came out of the box without any plugin...

Thanks a lot for your help :-)

[Gerrit0]

Yep, this is built in to TypeDoc. TypeDoc checks if your files are in a git repository pointing at GitHub, bitbucket, gitlab, and derives source urls from that. It can be controlled with the gitRemote and gitRevision option, or disabled with the disableSources option.

[Nclark89]

Hello Gerrit, thanks a lot for your support !

I actually tried this but it doesn't seem to do anything. Defined in is there but it's not an anchor:

Here's my typedoc.json with the gitRemote:

{ "entryPoints": ["./src/typedocEntry.ts"], "tsconfig": "./typedoc.tsconfig.json", "out": "jsdoc", "gitRemote": "https://cde.test.com/stash/projects/CARIT/repos/test/browse" }

The npm script:

"build-typedoc": "typedoc --options ./typedoc.json --customCss ./typeDocCss/style.css"

That I execute with "npm run build-typedoc"

and the typedoc version:

"typedoc": "^0.23.15",

After having a look into the source code it seems like there's a lot of processing and conditions before the url property gets set:

I'm not exactly sure why it isn't being set in my case but it might be good having an option that forces the url property to be set other than gitRemote(which doesn't seem to work in my case and seems to have a lot of other utilities)...

Thanks a lot for your support !

[Gerrit0]

The gitRemote option is meant to be given a remote name, not a url, I'm actually surprised that doesn't give an error message. That's definitely effectively disabling the plugin though.

https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/SourcePlugin.ts Is the relevant code, along with the imported Repository class. I'm not necessarily opposed to detecting urls in the gitRemote and treating them as a root to link documents too...

[Nclark89]

The gitRemote option is meant to be given a remote name, not a url, I'm actually surprised that doesn't give an error message. That's definitely effectively disabling the plugin though.

https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/SourcePlugin.ts Is the relevant code, along with the imported Repository class. I'm not necessarily opposed to detecting urls in the gitRemote and treating them as a root to link documents too...

Ah okey 👍 ! I can imagine quite some projects where the repository won't be resolved then if it's on a name spaced or private repo etc... Nice idea detecting gitRemote as a url and adding some extra logic in here to handle it:

https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/SourcePlugin.ts#L144

:-)

[Gerrit0]

Went to implement this, and noticed a potential issue...

typedoc/src/lib/converter/utils/repository.ts

Lines 180 to 189 in 0312504

	getLineNumberAnchor(lineNumber: number): string {
	switch (this.type) {
	default:
	case RepositoryType.GitHub:
	case RepositoryType.GitLab:
	return "L" + lineNumber;
	case RepositoryType.Bitbucket:
	return "lines-" + lineNumber;
	}
	}

I think I'll assume that #lines- should be used if bitbucket is in the url, and otherwise use #L

[Gerrit0]

Resolved with afd4afb

[Dayday10]

I want to thank all of you and tell you what a great job everyone is doing may all your blessings be filled with every thing in your life you want we only live once but if you live it right once is enough God bless you all. Shannon Day

…

On Tue, Oct 4, 2022, 2:50 AM Nclark89 ***@***.***> wrote: Hello Gerrit, thanks a lot for your support ! I actually tried this but it doesn't seem to do anything. Defined in is there but it's not an anchor: [image: image] <https://user-images.githubusercontent.com/36309447/193763684-a32f740f-c210-4fec-ade2-51198b59fcad.png> Here's my typedoc.json with the gitRemote: { "entryPoints": ["./src/typedocEntry.ts"], "tsconfig": "./typedoc.tsconfig.json", "out": "jsdoc", "gitRemote": " https://cde.test.com/stash/projects/CARIT/repos/test/browse" } The npm script: "build-typedoc": "typedoc --options ./typedoc.json --customCss ./typeDocCss/style.css" That I execute with "npm run build-typedoc" and the typedoc version: "typedoc": "^0.23.15", Thanks a lot for your support ! — Reply to this email directly, view it on GitHub <#2068 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AWMIKFM67DRUN6RP2VVSJWLWBPOUNANCNFSM6AAAAAAQ3ZVHKA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[Nclark89]

Went to implement this, and noticed a potential issue...

typedoc/src/lib/converter/utils/repository.ts

Lines 180 to 189 in 0312504

	getLineNumberAnchor(lineNumber: number): string {
	switch (this.type) {
	default:
	case RepositoryType.GitHub:
	case RepositoryType.GitLab:
	return "L" + lineNumber;
	case RepositoryType.Bitbucket:
	return "lines-" + lineNumber;
	}
	}

I think I'll assume that #lines- should be used if bitbucket is in the url, and otherwise use #L

Hello Gerrit0, when setting gitRemote to: "https://cde.mock-test.com/stash/projects/CARIT/repos/mock-test/browse" it generates https://cde.mock-test.com/stash/projects/CARIT/repos/mock-test/browse/b5aa28d/src/helpers/cssHelper/cssHelper.ts#L7 I'm not sure where b5aa28d comes from for /src/helpers/cssHelper/cssHelper.ts#L7 ? It seems like a kind of hash added in front of the file location...

Also "stash" is the previous bitbucket name(many projects using bitbucket might also be under a "stash" domain name): could we also handle it ? #L7 doesn't work for it it's just #7 :-) Thanks a lot for the enhancements so far !

[Gerrit0]

I originally forgot to update the site docs for gitRemote, but they now say:

This may be set to a URL (staring with http:// or https://), in which case TypeDoc will assume that it is the base URL for links. Links will be created to {gitRemote}/{gitRevision}/{filePath}.

I just created a dummy BitBucket cloud repo, went into a file, and clicked on a line, and got output like:

https://bitbucket.org/<user>/<repo>/src/<revision>/readme.js#lines-4

I don't have access to a non-cloud instance of Bitbucket anymore... if you change to a non-master branch, and click on a line, what does the url look like?

Adding "stash" for detection seems reasonable to me, PR welcome :)

[Nclark89]

I originally forgot to update the site docs for gitRemote, but they now say:

This may be set to a URL (staring with http:// or https://), in which case TypeDoc will assume that it is the base URL for links. Links will be created to {gitRemote}/{gitRevision}/{filePath}.

I just created a dummy BitBucket cloud repo, went into a file, and clicked on a line, and got output like:

https://bitbucket.org/<user>/<repo>/src/<revision>/readme.js#lines-4

I don't have access to a non-cloud instance of Bitbucket anymore... if you change to a non-master branch, and click on a line, what does the url look like?

Adding "stash" for detection seems reasonable to me, PR welcome :)

In my case the revision part is not needed, that might be bitbucket specific ?

In my case all I need is what is specified in gitRemote + the path resolved in the "Defined in":

Not sure why "src" is no longer part of the path in "Defined in {path}" but in the above case it would be:

So: {gitRemote}/src//helpers/cssHelper/cssHelper.ts however it adds the revision atm: {gitRemote}/src/{revision}/helpers/cssHelper/cssHelper.ts

[Gerrit0]

In my case the revision part is not needed, that might be bitbucket specific ?

BitBucket supports urls with revisions - it wouldn't be a version control system without that. TypeDoc includes the revision in urls because your documentation links should still point to functions even 6 months down the line when the codebase has completely changed.

This is why I asked:

if you change to a non-master branch, and click on a line, what does the url look like?

Not sure why "src" is no longer part of the path in "Defined in {path}" but in the above case it would be:

The path shown in "Defined in" is the shortest possible path to a file. If all your code was in packages/foo/lib, TypeDoc would treat that as the root of the displayed path.

[Nclark89]

Hello,

I get your point and it makes total sense but my repo is not on bitbucket but on stash that s why I don't think typedoc should treat it like bitbucket: if it doesn't recognize the type of repo from the url I believe it should just use the "gitRemote" url + path to file... in my case it would then work :-)

This is what I get by going to a feature branch:

https://cde.test.com/stash/projects/CARIT/repos/test/browse/src/helpers/cssHelper.ts?at=refs%2Fheads%2Ffeature%2Ftypescript-integration#6

And this is if I go to a specific commit:

https://cde.test.com/stash/projects/CARIT/repos/test/commits/4a3bdcd8e7fc9826fd3496de129230540628a0bf#src/helpers/cssHelper.ts

The revision typedoc uses is a shroter version which wouldn t even resolve in those urls commits url :s

Also, when you say "TypeDoc includes the revision in urls because your documentation links should still point to functions even 6 months down the line when the codebase has completely changed.": that s true but if your code-base changes, to me it sounds obvious devs should update typedoc too... on our side we generate a new typedoc output on each build of our branch and use the one from the latest master branch build :-)

[Gerrit0]

I think using gitRemote for this was a mistake. I should have gone with a new sourceLinkTemplate option which replaces {gitRevision}, {line} and {path} with appropriate values...

[Gerrit0]

Released in 0.23.17 ^

You should probably set:

{
  "sourceLinkTemplate": "https://cde.test.com/stash/projects/CARIT/repos/test/browse/{path}?at={gitRevision}#{line}"
}

The gitRevision will be the short version - git will still understand it, so should your stash instance should too.

[Nclark89]

Nice @Gerrit0 it now works :-) ! Small remark though:

I think the doc option is wrong there it's suppose to be sourceLinkTemplate :D

Thanks again for your updates !

[Gerrit0]

Oops! Thanks!