add homepage, repository, and documentation links to the pub result

[jakemac53]

Closes #154

This won't automatically include examples, as that would be a fair bit more involved, but it will include the documentation link if provided by the package.

[jakemac53]

cc @csells

[github-actions]

PR Health

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

[jakemac53]

One open question, should we default the documentation link to https://pub.dev/documentation/<package>/latest/?

Also, should we link to the actual pub page? That would show the readme content at least

[gspencergoog]

One open question, should we default the documentation link to https://pub.dev/documentation/<package>/latest/?

I think yes. The latest one is most likely the one most in use (especially for the majority of packages which haven't released in a while).

Also, should we link to the actual pub page? That would show the readme content at least

Maybe linking to the README itself might be more helpful? It'll be in Markdown, which the LLM would grok better anyhow, and because it's called "README" might be more attractive to the LLM to actually fetch and read.

[jakemac53]

Maybe linking to the README itself might be more helpful? It'll be in Markdown, which the LLM would grok better anyhow, and because it's called "README" might be more attractive to the LLM to actually fetch and read.

I am not sure we can reliably link to the README is the issue. We could potentially do that if the repo/homepage are GitHub links, as we know the rough structure of GitHub.

[jakemac53]

I think yes. The latest one is most likely the one most in use (especially for the majority of packages which haven't released in a while).

Separate but related question, should we just always include this, separate from the documentation link? I have noticed that if packages include a documentation link, it tends to be a custom page.

[gspencergoog]

I am not sure we can reliably link to the README is the issue. We could potentially do that if the repo/homepage are GitHub links, as we know the rough structure of GitHub.

In that case, I think the pub page is probably the next best thing.

[gspencergoog]

Separate but related question, should we just always include this, separate from the documentation link? I have noticed that if packages include a documentation link, it tends to be a custom page.

Would https://pub.dev/documentation/<package>/latest/<package>/ make sense (e.g. this one for Riverpod), since it's the "top" of the documentation tree for the API, and would list many more symbols?

[jakemac53]

Would https://pub.dev/documentation/<package>/latest/<package>/ make sense (e.g. this one for Riverpod), since it's the "top" of the documentation tree for the API, and would list many more symbols?

That won't always work for all packages because it assumes they have a file at lib/<package-name>.dart. Yes, most packages do have that, but not all.

[jakemac53]

Although, we actually do have the information to know all the public libraries, so we could link to each of their documentation pages.

[jakemac53]

Ok @gspencergoog I added docs links for all the libraries now :)

[jakemac53]

Another idea here is the keys in the libraries map could be package uris instead of just the library name?

[jakemac53]

cc @sigurdm do you know if the library names correspond to import paths (can we do package:<package-name>/<library-name>.dart always)? Or is there another way to get the import uri?

Update: Looks like it won't work out of the box today, https://pub.dev/documentation/test/latest/bootstrap_browser/ is an example, we just get the name browser for the library, it looks like this in the JSON:

{
    "name": "browser",
    "qualifiedName": "browser",
    "href": "bootstrap_browser/",
    "kind": 9,
    "packageRank": 0,
    "desc": ""
  },

We also can't get away with mangling the href (replace underscores with /) because that would break for libraries that actually have underscores in the name.

[gspencergoog]

Ok @gspencergoog I added docs links for all the libraries now :)

Nice!

[gspencergoog]

Update: Looks like it won't work out of the box today, pub.dev/documentation/test/latest/bootstrap_browser is an example, we just get the name browser for the library...

The pub.dev site must have a way to figure out all of the library links: it displays them. Can we ask them to add that info to the API?

[jakemac53]

The pub.dev site must have a way to figure out all of the library links: it displays them. Can we ask them to add that info to the API?

That is why I have cc'd @sigurdm on here :). It might be harder than you would think, those pages are dartdoc output which afaik you cannot get in a structured form. Clearly pub is already doing something here though to extract all the symbols in a package so hopefully it is possible to also provide the library imports.

[jakemac53]

I am going to go ahead and merge this as is but @sigurdm if you have thoughts please comment and I can follow up

[jakemac53]

Oh actually, I need approval from @gspencergoog first :)

[sigurdm]

LGTM