New :searchfox: role in source documentation

[Andrew Halberstadt]

Hey everyone!

When writing docs (for firefox-source-docs specifically), you may often find yourself wanting to link to Searchfox. A new role just landed which makes this a bit simpler. It can be used like so:

    See :searchfox:`here <devtools/client/definitions.js>` and :searchfox:`devtools/client/dom`.

The first role will create a link with the text `here`, and the second will create a link with the text `devtools/client/dom`. In both cases, they link to `https://searchfox.org/mozilla-central/source/<path>`.

You can also link to a separate tree on Searchfox like so:

    :searchfox:`here <mozilla-release:devtools/client/definitions.js>`

Here's an example of the role being used in the wild:

https://searchfox.org/mozilla-central/source/docs/code-quality/lint/linters/clang-format.rst#20

If you'd like to create a similar role (e.g to link to Bugzilla), it's pretty easy to do! See the implementation of the searchfox role for a hint.

Cheers,

Andrew

[Andrew Halberstadt]

I was mostly scratching an itch while working through some doc changes myself, so "planning" is a strong word. But those are good points and I've filed some bugs for both ideas:

* Detect broken links in the build

* Support permalinks in the searchfox role

Thanks!

- Andrew

On Wed, Jul 20, 2022 at 9:42 AM Gijs Kruitbosch <gijskru...@gmail.com> wrote:

Are we planning on doing some kind of automation that flags when linked files disappear to ensure the documentation doesn't have dead links?

Until now, when linking to searchfox, I've used permalinks to avoid that happening - but of course those gradually become old and more and more disconnected from current reality. Can the searchfox role create such permalinks?

~ Gijs

--
You received this message because you are subscribed to the Google Groups "firef...@mozilla.org" group.
To unsubscribe from this group and stop receiving emails from it, send an email to firefox-dev...@mozilla.org.
To view this discussion on the web visit https://groups.google.com/a/mozilla.org/d/msgid/firefox-dev/CAAJAz%2B6q9%2BT6Q6U4%3DN5utSONd5MekwprK475sWkxccsoH0MC9g%40mail.gmail.com.

[Chris H-C]

For those using MyST to write docs in the tree in markdown, the syntax[1] is

    {searchfox}`here <mozilla-release:devtools/client/definitions.js>`

I just added some docs using this and can confirm it works[2].

:chutten

[1]: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-an-in-line-extension-point

[2]: https://bugzilla.mozilla.org/show_bug.cgi?id=1780211

To view this discussion on the web visit https://groups.google.com/a/mozilla.org/d/msgid/firefox-dev/CAAJAz%2B7%2Bdah1yAwug8Ne%3DOQ9-D%2Bb%2BphfOdV%3DaOtKS2npWE6wag%40mail.gmail.com.