1780407 - Support permalinks in :searchfox: role

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Andrew Halberstadt [:ahal]]

Gijs pointed out that often permalinks are useful to avoid links becoming stale. This should be relatively straightforward to implement, just need to figure out a good format. Maybe something like:

:searchfox:`title <rev={rev}:{path}>`

This would then link to:
https://searchfox.org/mozilla-central/rev/{rev}/{path}

We probably want to support a generic way of specifying parameters for the case when we want rev and source. This might be useful for future non searchfox roles as well. Maybe:

:role:`{title} <{key1}={value1},{key2}={value2},...:{target}>`

So with :searchfox: with source and rev, it would be:

:searchfox:`title <source={source},rev={rev}:{path}>`

Comment 1

[Andrew Sutherland [:asuth] (he/him)]

I somewhat read Gijs question as to whether there might be some kind of magic to help ensure the links wouldn't be stale but to save people from having to indicate the revisions themselves. In terms of UX, if someone already has a searchfox permalink with revision, it seems like it would be less work for them to just use that link directly? The searchfox URL scheme is stable for the "rev" endpoint so there would never be a need to change the link that's generated. (That said I think the "searchfox" role makes sense for paths as a means of making the source more readable for those who are committed to writing docs in rST[1].)

In terms of magic that's possible, I think searchfox could some day provide:

• a /lastrev/ endpoint that could find the last revision that contained a file and redirect to that revision. This would be useful to look at deleted/moved files potentially.
• a /bydate/YYYYMMMDD/ mechanism that would locate the last revision on that date in UTC time and redirect to the revision. I might imagine that :Gijs would have been thinking about something like this, where if you knew the date the "searchfox" role link was added, you could build a URL with this scheme. Unfortunately I think this runs into traditional blame problems where line-centric blame easily becomes incorrect in the face of edits.

Note that searchfox does currently provide:

• /hgrev/HGREV/ so people can specify hg revisions and searchfox will look them up and redirect them.

Aside: A notable logistical issue is that currently searchfox does not provide computed directory contents for "/rev/", only files.

1: Context/Disclaimer: Searchfox is probably going to start processing markdown files in H2 and will ideally perform heuristic based processing of things in backticks to resolve them to in-tree paths and/or symbol names, so my personal recommendation to people would be to use markdown for docs since firefox-source-docs can render markdown too. Bug 1763532 tracks the notional plans for (markdown-only support for) this. I cringe at how this potentially could create a "this doc {designed for/reads best} in {firefox source docs/searchfox}" situation but given the current contributor situation in searchfox, targeting anything more than markdown is untenable.

Comment 2

[Andrew Halberstadt [:ahal]]

In terms of UX, if someone already has a searchfox permalink with revision, it seems like it would be less work for them to just use that link directly?

Yeah, I think I agree here. You'd have to permalink and then cut the revision out. I wouldn't mind WONTFIXing this if a /lastrev/ endpoint is unlikely to happen anytime soon.

so my personal recommendation to people would be to use markdown for docs since firefox-source-docs can render markdown too

Note that because we use myst to provide markdown support, I believe this role should be usable from markdown as well (though haven't tested it myself).

Edit: Tested and using:

{searchfox}`<path>`

works in firefox-source-doc's markdown as well!

Comment 3

[Andrew Sutherland [:asuth] (he/him)]

(In reply to Andrew Halberstadt [:ahal] from comment #2)

Yeah, I think I agree here. You'd have to permalink and then cut the revision out. I wouldn't mind WONTFIXing this if a /lastrev/ endpoint is unlikely to happen anytime soon.

I wouldn't rule it out! And if anyone is looking to implement this, I'm very happy to help mentor! :) Right now for hgrev we just shell out to git so if there's an easy git command (and we're careful to make sure it can't be used for shell shenanigans), we can maybe do that trivially!

Note that because we use myst to provide markdown support, I believe this role should be usable from markdown as well (though haven't tested it myself).

Edit: Tested and using:

{searchfox}`<path>`

works in firefox-source-doc's markdown as well!

Very cool! Unfortunately it seems like https://github.com/raphlinus/pulldown-cmark doesn't support that variation directly right now, but maybe the token stream is such that any searchfox processing could figure out the role and go from there. And if it can't figure out the role it could at least regexp match on the backtick contents to handle the tree/repo name and link word, etc.