1748845 - With MyST relative references to other components in firefox-source-docs are broken

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, defect)

Description

[Henrik Skupin [:whimboo][⌚️UTC+2] (away 10/03 - 10/13)]

Since bug 1746782 has been landed all the relative references at least in the /remote/doc and /testing/geckodriver/doc files are broken and links are no longer existent on rendered pages.

For example check mozconfig at:
https://firefox-source-docs.mozilla.org/testing/marionette/Building.html

There are a lot more references that are affected. Sadly it wasn't noticed when landing bug 1746782 that these are busted now. I wonder how more widespread this issue is.

Comment 1

[Andrew Halberstadt [:ahal]]

We could likely backout bug 1746782, though I wouldn't expect anyone to attempt re-landing (doc infrastructure is unowned).. so we'd lose out on the benefits myst provides and be on the deprecated recommonmark.

Afaict, the only other alternative is to fix the regressions. I don't think the fixes would be too hard, but I don't have time for it.. and if no one else has time, backing out might be the only option.

I can't resist mentioning that if I were maintaining docs in markdown.. I'd be very excited about myst :p

Comment 2

[Henrik Skupin [:whimboo][⌚️UTC+2] (away 10/03 - 10/13)]

Andrew, could you maybe repeat the proposed solutions as you mentioned on Element? Maybe you have some more information or an example too? I assume there is no solution that works for both? If we are going to update our own docs others might still be busted, and reverting the patch would render our changes as broken then.

Comment 3

[Andrew Halberstadt [:ahal]]

The options are outlined in comment 1.

As for examples, it depends on what you're trying to do, but there are some examples here:
https://myst-parser.readthedocs.io/en/latest/sphinx/use.html

Looks like you can link to docs like:

[link](path/to/doc.md)

You could also probably use the :doc: role (e.g in in rst) or the :ref: role (which is more robust than manually linking to a doc as it will survive renames).

But I've never used myst myself, so you'll have to experiment.

Comment 4

[BugBot [:suhaib / :marco/ :calixte]]

Set release status flags based on info from the regressing bug 1746782

Comment 5

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Fix geckodriver docs links,

Comment 6

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in remote docs,

These were broken since the update to MyST.

Comment 7

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in devtools docs,

Comment 8

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in testing docs,

Comment 9

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in rust docs,

Comment 10

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in dom docs,

Comment 11

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in performance docs,

These were broken since we adopted MyST.

Comment 12

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Update source-relative links in glean docs,

These were broken since the update to MyST.

Comment 13

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Remove @see links from JSDoc that didn't resolve to anything,

sphinx-js is apparently trying to link these to another object. In the interests
of removing all 'reference target not found' type warnings, I just removed the
@see annotations, since it wasn't trivial to work out if there was something
they could point at the would work in the generated docs.

Comment 14

[James Graham [:jgraham]]

Attachment: Bug 1748845 - Add a custom mechanism to make some docs warnings fatal,

The idea is to capture the warnings in a temporary file, and then
apply a set of regex to find any that should be treated as fatal.

This allows us to fix warnings one type at a time, and prevents us
regressing the warnings that are already fixed.

The "reference target not count" warning is added to the initial
forbidden list, so we can ensure we don't end up with internal links
pointing to nowhere.

Comment 15

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/d9b01f388d27
Fix geckodriver docs links, r=webdriver-reviewers,whimboo
https://hg.mozilla.org/integration/autoland/rev/72207858d8c7
Update source-relative links in remote docs, r=firefox-source-docs-reviewers,webdriver-reviewers,sylvestre,whimboo
https://hg.mozilla.org/integration/autoland/rev/dc15c73282cf
Update source-relative links in devtools docs, r=firefox-source-docs-reviewers,Honza,sylvestre
https://hg.mozilla.org/integration/autoland/rev/33babc343579
Update source-relative links in testing docs, r=firefox-source-docs-reviewers,ahal,sylvestre
https://hg.mozilla.org/integration/autoland/rev/e6b91230a0c0
Update source-relative links in rust docs, r=firefox-source-docs-reviewers,sylvestre
https://hg.mozilla.org/integration/autoland/rev/334f96cdbe67
Update source-relative links in dom docs, r=firefox-source-docs-reviewers,sylvestre,peterv
https://hg.mozilla.org/integration/autoland/rev/db2f5380d783
Update source-relative links in performance docs, r=firefox-source-docs-reviewers,sylvestre
https://hg.mozilla.org/integration/autoland/rev/8bf9a5e9580b
Update source-relative links in glean docs, r=firefox-source-docs-reviewers,chutten,sylvestre
https://hg.mozilla.org/integration/autoland/rev/d742452c2851
Remove @see links from JSDoc that didn't resolve to anything, r=rpl,firefox-source-docs-reviewers,sylvestre
https://hg.mozilla.org/integration/autoland/rev/6a3d6ade80e6
Add a custom mechanism to make some docs warnings fatal, r=ahal,firefox-source-docs-reviewers,sylvestre

Comment 16

[Sandor Molnar[:smolnar]]

https://hg.mozilla.org/mozilla-central/rev/d9b01f388d27
https://hg.mozilla.org/mozilla-central/rev/72207858d8c7
https://hg.mozilla.org/mozilla-central/rev/dc15c73282cf
https://hg.mozilla.org/mozilla-central/rev/33babc343579
https://hg.mozilla.org/mozilla-central/rev/e6b91230a0c0
https://hg.mozilla.org/mozilla-central/rev/334f96cdbe67
https://hg.mozilla.org/mozilla-central/rev/db2f5380d783
https://hg.mozilla.org/mozilla-central/rev/8bf9a5e9580b
https://hg.mozilla.org/mozilla-central/rev/d742452c2851
https://hg.mozilla.org/mozilla-central/rev/6a3d6ade80e6

Comment 17

[Ryan VanderMeulen [:RyanVM]]

Is this something we need on Beta too or is riding 98 to release sufficient?

Comment 18

[James Graham [:jgraham]]

I think riding the trains to release is fine; this only really affects https://firefox-source-docs.mozilla.org/ and not anything we ship to end users.